Command-line tool (CLI)

What the CLI is

spicyapi is a small program you run in a terminal, the window where you type commands instead of clicking buttons. Each command does one job: list the models your account can use, tell you what a generation will cost, start an image or video generation, wait for it to finish and give you a link to download the result.

You do not write any code. You type a command, press Enter and read the answer.

It is a good fit when you want to:

• try models and compare prices before anyone writes an integration;
• generate images or videos from your own computer and save the files;
• repeat the same kind of generation without clicking through a page each time;
• check a model's exact settings before you build something on top of it.

The CLI covers image and video generation. Text and chat models are called through the chat-compatible endpoints described in Text and streaming.

There are three other official tools. Pick the CLI if you want to type commands yourself:

Writing in another language? There are official SDKs for Python, Go, PHP and Java too.

What you can do

In the commands above, a word in angle brackets such as <task-id> means "put your own value here", without the brackets.

Before you start

You need four things: a terminal, Node.js, an API key and a way to run the CLI. This takes about ten minutes the first time.

node -v

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Your first result

This walkthrough generates one image and downloads it. Each step shows the command, roughly what you will see, and what just happened. Your numbers, IDs and times will differ.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

How to read the output

• Normal output shows one name: value per line. Values that contain several parts, such as output or retention, are printed as JSON on a single line.
• --json prints the complete answer as indented JSON. It works with every command, before or after the command name: spicyapi --json balance and spicyapi balance --json are the same.
• Results go to the screen's normal output; messages go to the error output. Prices, the idempotency key, the Accepted: lines and errors are messages. So spicyapi --json tasks get <task-id> > task.json saves only the result in task.json, while the messages still appear on screen.
• Errors look like Error: <what went wrong> (request req_…), usually followed by a Next: line that says what to do. With --json, an error is a one-line JSON object with error, type, status, code and requestId, and no Next: line. When no key is set, type is MissingApiKeyError. Quote the req_… value if you contact support.
• Money is a US dollar amount written as plain text without a $ sign, such as 0.03.
• Times are in UTC. The Z at the end of 2026-09-17T08:05:00Z means UTC.
• Exit status is 0 when a command succeeds and not 0 when it fails, which scripts can check.

Command reference

Every command also has built-in help: add --help, for example spicyapi tasks create --help.

Global options and environment variables

These options work with every command.

status

What it does: checks whether SpicyAPI is up and reachable from your computer.

spicyapi status

No options. No key needed. Free.

Output: one sentence. SpicyAPI is reachable — … answered in … ms. means everything is fine. could not be reached means your computer got no answer: check your network or proxy. is not healthy or reports it is not ready means a problem on our side; current incidents are listed at status.spicyapi.ai.

With --json you see the raw checks. operational: true is the answer that matters; a readiness entry with status 404 is normal on the public address.

docs search

What it does: finds the documentation page for a topic. It searches a small index built into the CLI, so it works without a key and without calling SpicyAPI. Each result links to the page on this documentation site, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

When there are several results, they are printed one after another, and each starts with slug:. If nothing matches, it says so and still exits with status 0:

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

With --json, no match prints an empty list, []. Free.

models list

What it does: lists the models your account can call today, with the prices your account pays.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Output: total and items. Use --json, because without it all items are printed on one line. The most useful fields of each item:

Free. The model list counts toward your account's request rate, so there is no need to run it before every generation.

models get

What it does: shows one model in full, including the settings it accepts.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Output: the same fields as models list, plus inputSchema. In inputSchema, read required (settings you must send), properties (every allowed setting and its type), enum (the only allowed values), minimum and maximum (number limits) and default (used when you leave the setting out). Entries named x-ui are hints for building forms; you can ignore them. Free.

balance

What it does: shows how much money is available on your account.

spicyapi balance

No options. Free.

Output: available (what you can spend now), held (set aside for tasks that are still running) and total, all in US dollars. It may also include funding, which splits the balance into prepaid funds and promotional grants, including when grants expire and which models they pay for. You do not need to check the balance before every generation: tasks create checks it for you.

usage

What it does: shows how many generations the current API key ran and how much they cost, grouped by day and by model.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

This covers all of September: --to is the first day that is not included. Leave out both options to see the last seven days, including today.

Output: from, to, currency, totalCalls, totalSpend, then days (per day: calls, succeeded, failed, spend) and models (the same numbers per model). totalSpend only counts final charges. days and models describe the same tasks in two ways, so do not add them together. For your whole account rather than one key, use the Usage page in the console.

Free. It is limited to 30 calls a minute, so use it to check totals, not in a loop.

tasks quote

What it does: tells you exactly what one generation would cost, without starting it and without setting any money aside.

spicyapi tasks quote --model <model> --input-file <path>

Output: quoteId, model, estimatedCost, maxCharge, currency, quantity (for example the number of seconds being charged), unit and expiresAt. A quote is valid for five minutes.

Free, no confirmation. Use it to compare models or settings. You do not have to run it before tasks create, which gets its own quote.

tasks create

What it does: starts an image or video generation. This costs money. The CLI always shows the price and asks first.

spicyapi tasks create --model <model> --input-file <path> [options]

What happens, in order:

1. The CLI reads your input and checks that it is a JSON object. If you gave no input, it stops here.
2. If nobody can answer a question, for example in a script, and you did not pass --yes, it stops here.
3. It gets a quote and prints the estimated charge, the maximum charge, when the quote expires and the idempotency key.
4. It asks Continue? [y/N]. Only y or yes continues. The default is no.
5. It creates the task at the quoted price. The estimated amount is set aside from your balance, and that amount is also the most the task can cost.
6. Without --wait, it prints idempotencyKey, taskId, state (queued), estimatedCost and deadlineAt, then returns. With --wait, it prints Accepted: <task-id> and a recovery command straight away, waits, then prints idempotencyKey, accepted and the finished task.

deadlineAt is the latest time the task can finish before it ends as expired. It is not when your download link or files expire.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

On macOS and Linux you can also give the input inline:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

When the wait fails with an error (rather than Ctrl + C), the last lines repeat everything you need, so you do not have to scroll back for the Accepted: line:

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

If the error was one with a known fix, such as 429 or a server error, a Next: line follows. With --json, the same facts are in the error object as taskId, idempotencyKey and recover.

tasks wait

What it does: waits for a task you already started, until it finishes.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Output: the finished task, with the same fields as tasks get, once its state is succeeded, failed or expired. If the task succeeded but its files are still being copied, it keeps waiting a little longer.

If the time limit runs out, you see Error: task … did not reach a terminal state within 600000ms. That is not a failure: the task is still running. Wait again, with a longer --wait-timeout-ms if needed. Stopping a wait never cancels a task. Free.

tasks get

What it does: shows one task right now: its state, cost, result links and when its content will be deleted.

spicyapi tasks get <task-id>

Use the same API key that created the task: another key gets "not found".

Output fields:

Normal output ends with a plain-language summary, such as Outputs expire: … or Content: Destroyed — you removed the outputs …. Each call returns fresh download links. Free.

tasks list

What it does: lists tasks created with the current API key, a page at a time.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Output: items (each with taskId, model, state, cost, settled, createdAt, deadlineAt and completedAt), hasMore and nextCursor. If hasMore is true, run the same command again with the same --from and --to, adding --cursor and the nextCursor value. The list has no download links; use tasks get for the task you want. Free.

tasks retry

What it does: runs a failed or expired task again, as a new task with a new ID. This costs money.

spicyapi tasks retry <task-id> [options]

It asks Retry source task … Continue? [y/N]. Unlike tasks create, it does not show a price before asking. The new task is charged at the model's current price, so check it first with spicyapi models get <model> if the price matters.

Output: idempotencyKey, the new taskId, sourceTaskId (the original), state, estimatedCost (the amount set aside) and deadlineAt.

• Only failed and expired tasks can be retried, plus older canceled ones. For another version of a successful result, use tasks create.
• The original input is reused unchanged, so a retry only helps when the failure was temporary. Check errorCode first; see Retry a failed task and Errors.
• If the input pointed at an uploaded file that has since expired, the retry fails; upload the file again and use tasks create.
• The retry keeps the original task's retention setting.
• If tasks create lost its connection before you saw a task ID, that is not a failed task. Use the recovery steps in Pick up a task after the wait was interrupted instead.

tasks purge

What it does: permanently deletes a finished task's generated media, result payload (the stored result data), prompt and other input text, right away instead of waiting for them to expire.

spicyapi tasks purge <task-id> [--yes]

A task that is still queued or running cannot be purged. It cannot be cancelled either — there is no cancellation command or API — so wait for it to finish with spicyapi tasks wait <task-id>, then purge it.

It explains what will be deleted and asks you to confirm, because it cannot be undone. Download anything you want to keep first.

Output: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (always true) and mediaDeletionPending, followed by a line naming what was destroyed and saying the stored media is removed within about a minute. If contentState is still present, nothing was removed this time; try again later.

Free, and not a refund: the ledger entry, charged amount, model, state, timestamps and request ID stay on record. See Retention and destruction.

files upload

What it does: uploads a file from your computer, such as the starting picture for an image-to-video generation, and gives you a spicy:// address to put in your input.

spicyapi files upload <path> [--content-type <type>]

Supported files are .jpg, .jpeg, .png, .webp and .gif images up to 10 MiB, .mp4 and .webm videos, and .mp3 and .wav audio up to 90 MiB and 600 seconds. A model can set lower limits of its own.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Output: copy the uri value exactly as printed into the model's file setting, often image_url. It can be used until expiresAt, normally one day. After that, upload the file again. Uploading is free.

files download-url

What it does: creates a new download link for a finished task's result. It prints the link; it does not save the file.

spicyapi files download-url <task-id> [--key <key>]

Output: key, url and expiresAt. The link works for about 20 minutes; open it in a browser or download it with curl. A task that has not succeeded yet answers "not found". If the file is still being copied you get a conflict error; wait a few seconds and try again. Once the task's files have been deleted, no new link can be made. Free.

webhooks verify

What it does: if you run a server that receives SpicyAPI callbacks (see --callback-url), this checks that one saved callback is genuine and unmodified. It runs entirely on your computer and needs no API key.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Output: on success, payload (the callback content), payloadVersion, taskId, deliveryId (version 2) and timestamp. If anything does not match, it prints an error and exits with a non-zero status. Free.

A signing secret is created automatically when you register, but its value is never shown. To get one you can copy, open Webhooks in the console and click Generate (or Rotate if one is configured). The new secret is shown only once. Rotating takes effect immediately, with no overlap: the old secret stops signing at once. See Webhooks.

Common recipes

Generate an image

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Pick an ID from the first command, build input.json from the settings shown by the second, then run the third and confirm with y. The walkthrough in Your first result explains each step.

Turn a picture into a video

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

The uploaded picture can be used for one day. After that, upload it again.

Pick up a task after the wait was interrupted

A task keeps running even if the terminal closes, the network drops, your computer sleeps or the wait times out. How you get back to it depends on what you saw:

• You saw Accepted: job_…, or a Recover: line under the error. You have the task ID. Wait again, or just look at it:

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• You only saw the Idempotency-Key: line, for example because the connection dropped while the task was being created. Run the same command again, with the same model and the same input, and add that key:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  The CLI shows the price and asks again, but if the first attempt was accepted, SpicyAPI hands back that same task instead of starting and charging for a second one. This works for 24 hours with the same API key. If the first attempt never arrived, the task is created now, once.

• You have neither. List your recent tasks and find it by time and model:

  spicyapi --json tasks list --limit 10

Retry a failed task

First find out why it failed:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Then read errorCode. 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. tasks retry sends the same input again, so it only helps when the cause was temporary:

The full list is in Errors.

When a retry makes sense, run it. It creates, and charges for, a new task:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Export your usage

Save a month of usage for the current key to a file:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

The file holds daily and per-model totals. For a task-by-task list, save spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100 in the same way, following nextCursor while hasMore is true. Account-wide figures and invoices are in the console.

Run the CLI from a script

In a script nobody can answer Continue? [y/N], so billable commands refuse to run unless you add --yes. When you do:

• quote first and check the price in the script;
• give every generation its own fixed --idempotency-key, such as poster-2026-09-17-v1, so that running the script twice does not charge twice;
• add --json and read state from the result: a command that exits with status 0 has not necessarily produced a successful task;
• set spending limits on the key in the console.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Costs, confirmation and safety

Which commands cost money. Only tasks create and tasks retry. Prices are in US dollars. Quoting, listing, checking, uploading, downloading and deleting are free.

Seeing the price first. tasks quote prices a request without starting anything. tasks create gets its own quote and shows Estimated charge and maximum charge before it asks. When the task is accepted, the estimated amount is set aside (held) and is also the most you can be charged. When the task succeeds you pay for what was actually produced, never more than that amount, and anything left over goes back to your balance.

The confirmation. Continue? [y/N] means the answer is no unless you type y. --yes answers for you, so only use it once you know the price. If the CLI runs somewhere that cannot ask, such as a script or with piped input, and there is no --yes, it refuses instead of assuming yes. tasks purge asks in the same way, because deleting cannot be undone. tasks retry asks too, but does not show a price first.

The idempotency key, in plain words. It is a label for one generation, like an order number. Every tasks create and tasks retry prints one. If your internet connection drops and you are not sure whether the generation started, run the same command again with --idempotency-key and the printed value: you get the original task back, and you are not charged twice. The label works for 24 hours with the same API key. Do not reuse it for a different generation: the same key with a different input is rejected.

No cancelling. Once accepted, a task cannot be cancelled. Ctrl + C, closing the terminal or revoking the key only stops the waiting; the task finishes and is charged normally.

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.

Download what you want to keep. Result files are kept for about 14 days at most, or less if your account or --retention says so, and then deleted for good. Download links last about 20 minutes, but you can always ask for a new one while the file exists. Uploaded files can be used for one day. Prompt text is erased after 30 days by default. Billing records are kept. See Retention and destruction.

Spending limits. Each key can have daily, monthly and lifetime limits, set on the API keys page. New keys have no limit until you set one. A task that would go over a limit is refused before it starts.

Your key. The CLI only reads the key from SPICY_API_KEY, never prints it, and in error hints shows at most its first nine characters (sk-spicy-).

More detail: Billing, Idempotency, Task commitment and retry.

Troubleshooting

Find the message you see. Errors from SpicyAPI end with (request req_…); include that value if you contact support, but never send your key.

Every error code is explained in Errors, and recovery steps are in Troubleshooting and recovery.

Source

The package is MIT-licensed and developed in the open at github.com/spicyapi-ai/spicy-cli. That is where to read the code behind any command on this page, report behaviour that differs from what is described here, or propose a change.

Next steps