How SpicyAPI works

Start here if you are new. This page explains what SpicyAPI does in plain words, helps you pick the way of using it that suits you, and introduces the handful of ideas that the rest of these docs assume. You do not need to know how to program to read it.

What SpicyAPI is

SpicyAPI gives you one API key for image, video and text models from many different model makers, and charges per use in US dollars.

Without it, using several AI models means opening an account with each company, learning each one's request format and topping up each one separately. With SpicyAPI you have one account and one balance. You pick a model, send your prompt (and a reference image if the model takes one), and get an image, a video or text back. Switching to another model does not change how you submit a request or collect the result.

• One key, many models. Every image and video model is used the same way: submit a task, then collect the result. Text models also accept the request formats of the official OpenAI, Anthropic and Google Gemini libraries.
• Pay per use, in dollars. Prices are per image, per second of video, per request or per token, depending on the model. There is no subscription and no credits or points system: the price you see is the dollar amount taken from your balance. There is no free tier either, so you add funds before your first generation. See Billing.
• When a task is accepted, its estimated cost is set aside from your balance. If it succeeds you pay for what it actually used, never more than that amount. Failed or expired tasks normally release the full hold. Some content refusals are charged at the accepted quote only when the model page explicitly discloses this exception. Check settled and cost for the final charge.
• No content switch to set. SpicyAPI does not require a content-mode request flag and does not perform per-request content review. What a model will produce depends on that model: some decline or tone down certain requests. You remain responsible for how you use what you generate; see Content and usage responsibility.

SpicyAPI does not serve mainland China, and a few other regions are restricted as well; see the same policy page.

What you can make

The catalog also carries a few more specialised video tasks, such as moving a character with the motion of another clip or extending an existing clip. Models are added and retired over time, so the live catalog is always the authority on what exists today.

To see the current models with pictures, descriptions and prices, open spicyapi.ai/explore. The same list is available without an account or a key as raw JSON, if you want to look at it from a terminal:

curl "https://api.spicyapi.ai/console/v1/catalog/models?locale=en&strict=1"

It prints a long block of text. Each model in it has a modality (image, video or text), its tasks and a starting price. That public list is for browsing; once you have a key, the list your key can actually call comes from GET /api/v1/models. See Catalog in the glossary.

Choose your path

There are five ways in. They all share one account, one balance, the same models and the same prices, so you can start with one and add another later.

Try it in your browser

• Good for: anyone who wants to see what a model does before deciding anything. Nothing to install, no code.
• You need: a web browser. You can open any model and fill in its form without an account. To press Run, you need to sign in and have a balance.
• Does it cost money? Each run is charged like an API call. Failed or expired tasks normally release the full hold. Some content refusals are charged at the accepted quote only when the model page explicitly discloses this exception. Check settled and cost for the final charge.
• Start: open spicyapi.ai/explore, choose a model and use the Playground tab on its page. Finished runs also appear under Logs in the console.

Ask your AI assistant

• Good for: people who already use an AI assistant such as Claude, Cursor, VS Code, Codex, Windsurf or Gemini CLI, and want to browse models, compare prices and generate images or videos by chatting. Developers also use it to explore before building.
• You need: Node.js 22.13 or newer, an API key and an assistant app that supports MCP. Paid steps only work in apps that can show you a confirmation question.
• Does it cost money? Browsing, quoting and looking up results are free. Starting or retrying a generation stops first and shows you the price; the assistant cannot answer that question for you.
• Start: MCP server gives the assistant SpicyAPI actions. The Agent Skill teaches an AI coding assistant to write SpicyAPI integrations the safe way, and works well alongside it.

Type commands in a terminal

• Good for: comparing prices, generating images and videos on your own computer and saving the files, repeating the same kind of job, or running a simple script. No programming.
• You need: a terminal, Node.js 22.13 or newer and an API key stored in the SPICY_API_KEY environment variable.
• Does it cost money? Only spicyapi tasks create and spicyapi tasks retry can charge you, and both ask before anything is charged.
• Start: Command-line tool (CLI).

Build node workflows in ComfyUI

• Good for: people who already work in ComfyUI and want hosted models next to their local nodes: chain an image model into a video model, add a soundtrack, or let a chat model write the prompt.
• You need: ComfyUI on your computer or a server, and an API key. SpicyAPI's models run on our servers, so no GPU is needed for them.
• Does it cost money? Each run is charged like an API call. Every node shows its rate, quotes before it runs, and can stop any run above a limit you set.
• Start: ComfyUI nodes.

Write code

• Good for: adding image, video or text generation to your own app, website backend or data pipeline.
• You need: code that runs on a server or your own computer, because an API key must never be placed in a web page or a mobile app. There are official SDKs for TypeScript (Node.js 22.13 or newer), Python 3.11+, Go 1.23+, PHP 8.1+ and Java 17+; any other language can call the HTTP API directly.
• Does it cost money? Every accepted generation is charged. Quotes, catalog reads and task lookups are free.
• Start: TypeScript SDK for Node.js, or the Python, Go, PHP and Java SDKs. For plain HTTP with curl, Node.js, Python and Go examples, use the Quickstart; see Text and streaming for chat models and the image-to-video tutorial for a complete worked example.

Ideas you will meet everywhere

You do not need any of this to try the Playground, but every other page assumes it. Each idea gets a sentence or two here, a link to the page that owns the details, and a longer plain-language entry in the glossary.

What happens when you generate something

1. You pick a model and fill in its inputs.
2. Optionally, you ask for a quote: the exact price, for free.
3. You submit. SpicyAPI accepts the request as a task, gives you a task ID and sets the estimated cost aside from your balance.
4. The model works in the background. Images usually take seconds; videos often take minutes.
5. The task finishes. If it succeeded, you pay for what it actually used, never more than the amount set aside. Failed or expired tasks normally release the full hold. Some content refusals are charged at the accepted quote only when the model page explicitly discloses this exception. Check settled and cost for the final charge.
6. You collect the result, either because SpicyAPI calls your server back or because you ask, and you download the file. Download links are temporary and files are kept for a limited time, so save what you want to keep.

Model ID

Every model has an exact ID of the form publisher/model/task. Copy it from the live catalog (GET /api/v1/models, spicyapi models list or listModels()) rather than from memory or a web page: models get added, paused and retired. Code examples in these docs write MODEL_ID_FROM_CATALOG where a real ID goes. Model catalog and schemas · Glossary: model ID

Tasks and their states

Image and video generation is asynchronous: submitting and collecting the result are two separate steps, linked by a task ID that starts with job_. A task moves from queued to running and ends as succeeded, failed or expired; anything other than queued or running is final. Text models answer on the same connection instead, often word by word. Asynchronous tasks · Text and streaming · Glossary: task state

Quote

A quote prices your exact request without starting anything or setting money aside. It is valid for five minutes. If you submit with it and the price or the request has changed in the meantime, the submission is refused rather than charged at a different amount. Quotes and compatibility · Glossary: quote

Idempotency key

A label you choose for one piece of work and send with it. If your connection drops and you send the same request again with the same label and the same API key within 24 hours, you get the original task back instead of starting and paying for a second one. The CLI and the MCP server create one for you; with the SDK or plain HTTP you pass your own. Idempotency · Glossary: idempotency key

Callbacks

Instead of asking again and again whether a task has finished, you can give it a callBackUrl: a public HTTPS address on your server. When the task finishes, SpicyAPI sends the result there, signed so you can check it really came from SpicyAPI. Asking repeatedly, called polling, is fine while you are testing on your own computer. Webhooks · Glossary: webhook

How long results are kept

A result's download link lasts about 20 minutes; ask for the task again to get a fresh one. Generated files are kept for about 14 days at most, uploaded files for one day and prompt text for 30 days, and you can shorten all three or destroy one task's content on demand. Billing records are kept much longer. Download anything you want to keep. Retention and destruction · Glossary: retention

Balance and spend caps

Your balance is prepaid US dollars. Every API key can also have a daily, monthly and lifetime spend cap that you set. When your balance cannot cover a task you get error 40201; when a cap is reached you get 40202. Neither creates a task or charges anything. Billing · Authentication · Glossary: spend cap

Your first time, in order

Where to get help

• Quick answers: FAQ, Glossary, Troubleshooting and Errors.
• Is the service up? status.spicyapi.ai.
• Talk to us: open a conversation on the console's Support page, or use the contact page. Include the request_id or task ID and the time in UTC. Never send your API key.

Next