Glossary

These docs use technical words because the product is an API. This page explains each of them in plain language, in alphabetical order. Every entry has three parts: what the word means in general, what it means in SpicyAPI, and the page that has the full details.

Other pages link straight to an entry, so if a word stops you somewhere else, it is probably here. For the bigger picture, start with How SpicyAPI works.

Agent Skill

A folder of written instructions that an AI coding assistant reads before it works on a task, like an operations manual handed to a new colleague. It contains no program and does nothing on its own.

In SpicyAPI: the official Skill, published as @spicyapi/skill, teaches assistants such as Claude Code, Codex or Cursor how to use SpicyAPI correctly: read the live catalog instead of guessing, show you the price before paid work, reuse idempotency keys and never paste your API key into code. Install it with npx skills add spicyapi-ai/spicy-skill. It works well together with the MCP server.

See: Agent Skill

API

Short for application programming interface: a fixed set of requests one program can send to another, and the answers it gets back. A website is made for people to click; an API is made for programs to call.

In SpicyAPI: the API is how every tool reaches the models. The Playground, the CLI, the MCP server and the SDK all send the same kinds of requests to api.spicyapi.ai that your own code can send.

See: OpenAPI and endpoint index

API key

A secret string that proves a request comes from you. Treat it like a password that programs use.

In SpicyAPI: keys start with sk-spicy- and are created on the console's API keys page. A key is shown only once; if you lose it, create a new one. Each request sends the key in the Authorization: Bearer header. Keep keys on your own computer or server, never in a web page, mobile app, public repository, screenshot or chat. Each key can have its own spend caps, a list of allowed models and a list of allowed IP addresses.

See: Authentication · Set up your account

Asset and output URL

An asset is one file a task produced, such as an image or a video. Its output URL is the web address you download it from.

In SpicyAPI: a finished task lists its files in output.assets[]. Each has a url you can download directly, without your API key, plus expiresAt, mime (the file type) and size details. The link lasts about 20 minutes; ask for the task again to get a fresh one. The file itself is kept for about 14 days at most, so save a copy of anything you need. An asset marked pending: true is still being stored (try again in a few seconds); one marked unavailable: true is gone for good.

See: Asynchronous tasks · Media

Balance

The money in your account that pays for generations.

In SpicyAPI: a prepaid balance in US dollars, with no credits or points. What you pay in never expires; promotional credit has its own expiry date. You add funds on the console's Billing page. GET /api/v1/chat/credit returns three amounts as text such as "128.42": available (free to spend), held (set aside for tasks still running) and total. Some accounts also have promotional grants or an approved credit facility, which appear as a separate breakdown. There is no free tier: new accounts start at zero.

See: Billing · Set up your account

Base URL

The fixed first part of every address an API uses. You write it once in your code or tool settings, and each request adds its own path after it.

In SpicyAPI: there are two.

Requests in the Google Gemini format go to https://api.spicyapi.ai/v1beta. The official Anthropic and Google GenAI libraries add the version part themselves, so for them you set just https://api.spicyapi.ai.

See: Quickstart · Text and streaming

Callback

Another name for a webhook. In SpicyAPI the address is passed in the callBackUrl field when you create a task.

Catalog

The list of models on offer, with their prices and the inputs each one accepts.

In SpicyAPI: there are two versions of the same list.

• The public catalog needs no account or key. It is what spicyapi.ai/explore shows and what GET /console/v1/catalog/models returns. Use it to browse and compare.
• The authenticated catalog, GET /api/v1/models with your API key, is the only reliable source of the models your key can call right now, at your account's prices. Before paid work, pick an item whose enabled and available are both true.

The CLI command spicyapi models list, the SDK method listModels() and the MCP tool spicyapi_models_list all read the authenticated catalog.

See: Model catalog and schemas

CLI

Short for command-line interface: a program you use by typing commands in a terminal instead of clicking buttons.

In SpicyAPI: the spicyapi command, published as @spicyapi/cli, lets you list models, check prices, create image and video tasks, wait for them and download the results without writing code. Only tasks create and tasks retry cost money, and both ask you first. It needs Node.js 22.13 or newer; you can run it with npx @spicyapi/cli without installing it.

See: Command-line tool (CLI)

Endpoint

One specific request an API accepts, named by an HTTP method (such as GET to read or POST to send) and a path.

In SpicyAPI: for example, POST /api/v1/jobs/createTask starts a generation and GET /api/v1/jobs/recordInfo reads a task. The full address is the base URL followed by the path.

See: OpenAPI and endpoint index

Envelope

A fixed outer wrapper that every response is placed in, so a program always knows where to look.

In SpicyAPI: native API responses (under /api/v1) look like this:

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code is a business code (200 means success), msg is a human-readable message, data holds the answer and is left out entirely on failure, and request_id identifies this request. The OpenAI-, Anthropic- and Gemini-compatible endpoints use their own protocols' shapes instead.

See: Errors

Environment variable

A named value that your terminal hands to every program it starts. It lets a program read a setting, such as a secret key, without the value being written into a file or a command.

In SpicyAPI: the SDK, CLI, MCP server and the code examples in these docs read your API key from a variable named SPICY_API_KEY. To set it for the current terminal window:

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

That setting is forgotten when you close the window. The CLI page shows how to make it permanent and how to check it without printing the whole key.

See: CLI: before you start · Set up your account

Error code

A short, fixed value that tells a program what went wrong, so it can react without reading the message text.

In SpicyAPI: there are two kinds.

• code in the envelope describes the request itself. 200 is success; others include 400 (invalid request), 401 (key problem), 40201 (balance too low), 40202 (a spend cap was reached) and 429 (too many requests). It is a business code, which is more specific than the HTTP status sent alongside it.
• errorCode appears on a task that was accepted but then failed. It is one of nine values: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset or upstream_failed.

The matching messages, msg and errorMessage, are for people: their wording can change, and they can be returned in your chosen language. Programs should branch on the codes only.

See: Errors

Hold, settle and release

The three steps of paying for a task. A hold is money set aside but not yet spent, like a hotel holding an amount on your card.

In SpicyAPI:

• Hold: when a task is accepted, its estimated cost (estimatedCost) is set aside from your balance and shows as held. It is not a charge yet, and it is also the most this task can ever cost.
• Settle: when the task succeeds, you are charged for what it actually used, never more than the hold. Anything left over goes back to your available balance. settled: true on the task means the amount in cost is final.
• Release: 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.

See: Billing

HTTP status

A three-digit number at the start of every web response that says, broadly, how the request went. 2xx means it worked, 4xx means something about the request was wrong, and 5xx means the server had a problem.

In SpicyAPI: creating a task answers 202 Accepted, meaning the task was accepted, not that it has finished. Native responses also carry a more specific business code: for example, a balance that is too low is HTTP 402 with code 40201. Pick one of the two to branch on in your code, and stick to it.

See: Errors

Idempotency key

A label you invent for one piece of work, so that sending the same request twice does the work only once. The word idempotent means that doing something again has no further effect.

In SpicyAPI: send it in the Idempotency-Key header when you create or retry a task, for example order-8814-render-1. If your connection drops and you are not sure the task started, send the same request again with the same key and the same API key within 24 hours: you get the original task back, and you are not charged twice. Use a new key for each new piece of work. Reusing a key with a different request is refused with 409. Keys can be up to 128 characters.

See: Idempotency

Input schema

A machine-readable description of which fields a request may contain, what type each one is and which values are allowed.

In SpicyAPI: every model has its own inputSchema, written in JSON Schema. It lists the fields you can put in input, such as prompt, image_url or duration_seconds, with their limits and defaults. The server checks every request against it, and one unknown field is a 400 error. The Playground builds its form from the same schema, and examples in the catalog are complete inputs that have already passed it.

See: Model catalog and schemas · Spicy Schema

JSON

A plain-text format for structured data, made of names and values in curly braces. Almost every API uses it, because every programming language can read it.

In SpicyAPI: requests and responses are JSON. A minimal task request looks like this:

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG stands for a real model ID taken from the live catalog. Money is always sent as text, such as "0.008", so no amount is ever rounded by accident.

See: Quickstart

MCP

Short for Model Context Protocol: an open standard that lets AI assistants load extra abilities, called tools, from small programs called MCP servers.

In SpicyAPI: the official server, @spicyapi/mcp, runs on your own computer and gives assistants such as Claude, Cursor, VS Code or Codex 15 SpicyAPI tools: browse models, get quotes, create tasks, upload files and fetch results. Starting, retrying or destroying a task stops and asks you to confirm, showing the price where there is one; the assistant cannot answer for you. It needs Node.js 22.13 or newer.

See: MCP server

Modality

The kind of media a model works with.

In SpicyAPI: each catalog entry has a modality such as image, video or text, and a list of tasks such as text-to-image or image-to-video. Filter the catalog with them, for example GET /api/v1/models?modality=video&task=image-to-video.

See: Model catalog and schemas

Model ID

The exact name you send to choose a model.

In SpicyAPI: IDs have the form publisher/model/task: who made the model, which model and version, and what the endpoint does. Image editing endpoints end in edit. Always copy an ID from the live catalog (GET /api/v1/models, spicyapi models list or listModels()), never from memory or a web page, because models are added, paused and retired. Examples in these docs write MODEL_ID_FROM_CATALOG where a real ID belongs; sending that placeholder itself fails.

See: Model catalog and schemas

Node.js

A free program that runs JavaScript outside a web browser. Many developer tools are written in JavaScript and need it installed.

In SpicyAPI: the SDK, the CLI and the MCP server need Node.js 22.13 or newer; the installer the Skill uses asks for 22.20 or newer. Install the LTS version from nodejs.org, then check it in a terminal with node --version. You do not need Node.js for the Playground, or if you call the API from another language.

See: CLI: before you start

npm and npx

npm is the package manager that comes with Node.js: it downloads and installs JavaScript packages. npx, which comes with it, runs a package without installing it permanently.

In SpicyAPI: the four Node.js tools are npm packages: @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp and @spicyapi/skill. For example, npm install @spicyapi/sdk adds the TypeScript SDK to a project, and npx @spicyapi/cli status runs the CLI once without installing it. The Python, Go, PHP and Java SDKs are installed by their own ecosystems' tools instead; see each SDK's page.

See: TypeScript SDK · Command-line tool (CLI)

OpenAI-compatible

Accepting requests in the same format as OpenAI's API, so software written for OpenAI works after changing only the address and the key.

In SpicyAPI: text models can be called through POST /v1/chat/completions and POST /v1/responses in the OpenAI format, POST /v1/messages in the Anthropic format and /v1beta/models/… in the Google Gemini format, all with the same API key. Point the official openai library at https://api.spicyapi.ai/v1. Any text model works with any of these formats. These endpoints charge the price in force when the request is accepted and do not take a quote, so set spend caps on the key.

See: Text and streaming

Playground

A form on a website where you can try a model by filling in fields and pressing a button, without writing code.

In SpicyAPI: every model page on spicyapi.ai has a Playground tab. You can fill in the form and see the request it builds without an account; running it requires signing in and a balance. Each run shows its estimated cost first, is charged like an API call, and appears in the console's Logs.

See: How SpicyAPI works

Polling

Asking a server again and again whether something has finished, instead of waiting to be told.

In SpicyAPI: you poll a task with GET /api/v1/jobs/recordInfo?taskId=… until its state is no longer queued or running. Wait 2 to 3 seconds before the first check, make each wait about 1.5 times longer up to 10 to 15 seconds, and give up waiting at a deadline you choose. Giving up does not stop the task. Polling counts against your rate limit, so in production prefer a webhook.

See: Asynchronous tasks

Purge

Permanently deleting stored content on request, rather than waiting for it to expire.

In SpicyAPI: POST /api/v1/jobs/purge (or Destroy outputs in the console's Logs, spicyapi tasks purge, purgeTask()) deletes a finished task's generated files, its result and the prompt text in its input. The billing record stays: amount, model, state, timestamps and request_id. Purging is not cancelling and does not refund anything, and it cannot be undone. It only works on tasks that have finished.

See: Retention and destruction

Quote

A price calculated in advance for one exact request.

In SpicyAPI: POST /api/v1/jobs/quote takes the same body you would submit and returns estimatedCost, maxCharge and expiresAt, without creating a task or setting money aside. It costs nothing and is valid for five minutes. If you submit with the returned quoteId and expectedCost and the request or price has changed, the submission is refused with 40901 instead of charging a different amount. The CLI and the MCP server get a quote automatically before they create a task.

See: Quotes and compatibility

Rate limit

A ceiling on how many requests you may send in a period of time, so that one runaway program cannot overload a service.

In SpicyAPI: the native API allows, by default, 1,000 requests per 10 seconds per account for reads and the same again for writes, each shared by all of the account's keys. Polling counts as a read, so a busy polling loop cannot stop your task submissions from going through. Going over returns 429 with a Retry-After header saying how many seconds to wait. The limit counts requests, not tasks: tasks that are already running do not use it up.

See: Rate limits

request_id

An identifier the server attaches to one request, so that request can be found again in logs.

In SpicyAPI: every native response carries request_id (for example req_01k3…), also sent in the X-Request-Id header, on success and failure alike. Keep it in your logs and include it when you contact support. In a version 2 webhook, request_id identifies that delivery instead (whd_…) and stays the same when the delivery is retried.

See: Errors · Webhooks

Retention

How long stored data is kept before it is deleted.

In SpicyAPI:

You can shorten how long generated files, uploads and prompt text are kept on the console's Data protection page, or for one task with the X-Spicy-Retention header, and destroy content at any time with purge. Nothing you set makes a period longer.

See: Retention and destruction

SDK

Short for software development kit: a ready-made code library you add to your own program, so you do not have to build every request by hand.

In SpicyAPI: there are five official SDKs — @spicyapi/sdk for TypeScript and JavaScript on Node.js, plus one each for Python, Go, PHP and Java. Each handles the key, waiting for tasks, retries, uploads and webhook checks, so a couple of calls take a task from submission to result. They all run on servers only, not in browsers or mobile apps, and none of them covers chat models.

See: TypeScript SDK · Python SDK · Go SDK · PHP SDK · Java SDK

Signature (HMAC)

A code computed from a message and a shared secret, so the receiver can check that the message is genuine and was not changed on the way. HMAC is the standard method for computing one.

In SpicyAPI: every webhook delivery carries an X-Webhook-Signature header: an HMAC-SHA256 over the task ID, the delivery time and a digest of the exact body, made with your webhook signing key. You generate or rotate that key on the console's Webhooks page, and it is shown only at that moment; if you never copied it, rotate it there. Check the signature before trusting a delivery, using verifyWebhook from the SDK or spicyapi webhooks verify, and reject deliveries whose timestamp is more than five minutes away from the current time.

See: Webhooks

Spend cap

A spending ceiling you set in advance, so a mistake or a leaked key cannot use up your whole balance.

In SpicyAPI: each API key can have a daily, a monthly and a lifetime cap in US dollars, set by you; new keys have none until you add one. Teams can add daily and monthly budgets, and the platform has its own daily limit. A task that would go over any of them is refused with 40202 before it starts, and nothing is charged. Daily caps restart at 00:00 UTC and monthly caps on the 1st of the month; lifetime caps never restart. Entering 0 means no cap at that level.

See: Billing · Authentication

Streaming (SSE)

Sending an answer piece by piece as it is produced, over one open connection, instead of all at once at the end. SSE, short for server-sent events, is the common web format for this.

In SpicyAPI: text models can stream their reply word by word through the compatible endpoints (for example stream: true on /v1/chat/completions) or the native POST /api/v1/jobs/stream. Each protocol marks the end of a stream in its own way. Closing the connection early stops you receiving the text but does not stop the model, and the usage is still charged. Streamed text is not stored, so it cannot be fetched again later.

See: Text and streaming

Task

One unit of work that runs in the background: you hand it over, and collect the result later.

In SpicyAPI: every image or video generation is a task. POST /api/v1/jobs/createTask accepts it and returns a task ID starting with job_; you then poll the task or receive a webhook when it finishes. Through the API, a task can only be read with the same API key that created it; the console's Logs page shows all of your account's tasks. An accepted task cannot be cancelled.

See: Asynchronous tasks · Task commitment and retry

Task state

Where a task is in its life.

In SpicyAPI:

Older records can also show canceled, which new tasks never reach. Treat any state other than queued or running as a terminal state.

See: Asynchronous tasks

Terminal

A text window where you type commands and press Enter to run them. On macOS it is the Terminal app; on Windows use PowerShell; most Linux desktops open one with Ctrl + Alt + T. Not to be confused with a terminal state.

In SpicyAPI: you use a terminal to run the CLI, to install Node.js tools such as the MCP server or the Skill, and to try the curl examples in these docs.

See: CLI: before you start

Terminal state

A final state: once a task reaches it, it never changes again.

In SpicyAPI: any task state other than queued or running is terminal: succeeded, failed, expired and, on older records, canceled. Test for "not queued and not running" rather than listing the final states, so your code keeps working if a new one is added. Webhooks are sent only when a task reaches a terminal state. Only finished tasks can be purged, and failed or expired tasks can be retried.

See: Asynchronous tasks

Upload

Sending a file from your computer to a server so it can be used there.

In SpicyAPI: a model that takes an image, video or audio input can receive it in three ways: a public HTTPS link to the file, a small image embedded in the request as a data URI (up to 1 MiB), or an uploaded file. Uploading takes three steps: request a ticket (POST /api/v1/common/upload-url), send the file to the address in the ticket, then commit it (POST /api/v1/files/{fileId}/commit). The commit returns a spicy:// address to put in the model's input field. It can be used for one day. Images can be up to 10 MiB, and audio or video up to 90 MiB and 600 seconds. uploadFile() in the SDK, spicyapi files upload and the MCP server do all three steps for you.

See: Media

Webhook

An address on your own server that another service calls when something happens, so you do not have to keep asking. Also called a callback.

In SpicyAPI: put a public HTTPS address in callBackUrl when you create a task. When the task reaches a terminal state, SpicyAPI sends a POST request there with the same content recordInfo would return, signed with your webhook signing key. Reply with any 2xx status within 15 seconds; otherwise the delivery is retried, up to eight attempts over roughly nine hours, and you can resend it from the console's Webhooks page. There is no notification when a task merely starts. Local addresses such as http://localhost:3000 cannot receive webhooks, so poll instead while developing on your own computer.

See: Webhooks

Workspace and team

A shared space where several people use the same keys, tasks and budgets under one account.

In SpicyAPI: a team workspace has members with roles: owner, admin, developer, billing and readonly. Every member can see task summaries and usage; owner, admin and developer can also see task inputs and results. The owner's account pays for the team's new tasks, and members never see the owner's own balance or payments. Teams can set daily and monthly budgets.

See: Console and teams