OpenAPI and endpoint index
Downloadable OpenAPI 3.1 contract, every public endpoint with the guide that explains it, the shared request headers, and the production origin.
The machine-readable public contract is available as OpenAPI 3.1 YAML. Use it to generate a client or validate your integration against the current public endpoints.
Production API origin
https://api.spicyapi.ai is the only production origin declared by OpenAPI servers[0].url. Task APIs use /api/v1; protocol compatibility uses /v1 and /v1beta.
These platform APIs support model selection, estimates and spend monitoring without opening the Console. The model catalog includes account pricing; use an exact-input quote when the price depends on parameters. Task history and usage are scoped to the API key you call with. Key creation, rotation and budget settings remain in the Console. Each table links to the guide that explains the endpoint in full.
Model discovery, pricing and account APIs
| Method | Path | Purpose | Guide |
|---|---|---|---|
GET | /console/v1/catalog/models | Public catalogue for evaluation: no API key, standard prices, rate-limited by source address | Quickstart |
GET | /api/v1/models | Read callable models, account prices, and optional schemas | Model catalog |
GET | /api/v1/models/{model} | Read one model and its complete JSON Schema | Model catalog |
POST | /api/v1/jobs/quote | Quote the exact request for five minutes without creating a task or holding funds | Quotes |
GET | /api/v1/chat/credit | Read available, held, and total balance | Billing |
GET | /api/v1/usage | Read current-key calls and settled USD spending by date and model | Billing |
Generation and task APIs
| Method | Path | Purpose | Guide |
|---|---|---|---|
GET | /api/v1/jobs | List the current API key's task history with cursor pagination | Tasks |
POST | /api/v1/jobs/createTask | Create an asynchronous generation task | Tasks |
GET | /api/v1/jobs/recordInfo | Read a task created with the calling API key | Tasks |
POST | /api/v1/jobs/retry | Create a new task from a failed or expired task; historical canceled records remain compatible | Task actions |
POST | /api/v1/jobs/purge | Destroy one terminal task's artefacts and prompt; the billing record is untouched | Retention |
POST | /api/v1/jobs/stream | Run a text model and stream the answer over SSE | Text and streaming |
Media APIs
| Method | Path | Purpose | Guide |
|---|---|---|---|
POST | /api/v1/common/upload-url | Issue a direct media-upload ticket | Media |
POST | /api/v1/files/{fileId}/commit | Verify and commit a direct upload, returning the task-ready spicy:// URI | Media |
POST | /api/v1/files/import | Import a LoRA weights file from a link, with an optional access token used once and never stored; returns a task-ready spicy:// URI | Adapter weights |
POST | /api/v1/common/download-url | Issue a short-lived task-output download URL (optional: finished tasks already include one) | Media |
POST | /api/v1/assets | Save a file to your asset library (Idempotency-Key required) | Media |
GET | /api/v1/assets | List your saved assets (filter by favorite, collectionId, q; sort with sort) | Media |
GET | /api/v1/assets/usage | Show your asset library plan, usage and limits | Media |
GET | /api/v1/assets/{assetId} | Get one asset with a fresh private preview link | Media |
PATCH | /api/v1/assets/{assetId} | Rename an asset or change its favorite flag | Media |
DELETE | /api/v1/assets/{assetId} | Delete an asset | Media |
GET | /api/v1/assets/entities | List the characters in your asset library (read-only) | Media |
GET | /api/v1/assets/entities/{entityId} | Get one character with its images in order (read-only) | Media |
Authentication and envelopes
Every endpoint except the public catalogue requires your API key as Authorization: Bearer sk-spicy-…; the compatibility endpoints (/v1, /v1beta) also accept x-api-key, as sent by Anthropic SDKs, and x-goog-api-key, as sent by Google GenAI SDKs. A key in the URL query string is never accepted. Tasks, retries, purges and download links are visible only to the API key that created the task; see Authentication.
Task API JSON responses share the {code,msg,data,request_id} envelope; the compatibility endpoints use their protocols' own shapes. A task's outcome is expressed by data.state, not the envelope code. See Errors.
Request headers used across endpoints
| Header | Sent to | Purpose |
|---|---|---|
Authorization: Bearer … | Everything except the public catalogue | Your API key |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos and the /v1 and /v1beta text endpoints | Makes a resend after a network error safe. On task endpoints it returns the original task; on text endpoints it prevents a second charge but cannot return a lost answer. See Idempotency |
X-Spicy-Retention | jobs/createTask, jobs/stream | Shortens how long this task's outputs and prompt are kept, in seconds. See Retention |
Accept-Language | Any | Language of error messages; codes never change. See Errors |
Using the OpenAPI file
- Try requests without writing code: import the OpenAPI file linked at the top of this page into an API client such as Postman, Insomnia or Bruno, then set the bearer token to your API key. Remember that creating tasks costs money.
- Generate a client: feed the same file to an OpenAPI 3.1 code generator for your language.
Contract changes
- Do not preserve model parameters as a permanent hard-coded snapshot; read
inputSchemafrom/models/{model}. - Be tolerant of unknown response fields, but never guess unknown request fields.
- Feed the OpenAPI YAML into code generation or contract tests before release.
Compatibility endpoints
| Method | Path | Protocol |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Video status |
GET | /v1/videos/{videoId}/content | Video content |
Text endpoints are covered in Text and streaming; how they are priced is in Quotes and compatibility.
The official TypeScript package is @spicyapi/sdk. For Python and Go, or if you cannot add a dependency, the copyable reference clients below call these endpoints with nothing but the language runtime. The Python one carries a whole media job on its own: upload and commit a reference file, confirm the price with a quote, create the task and poll it to a terminal state, read the result whether it is files or text, refresh an expired output link, destroy the stored content afterwards, and verify a webhook signature. The Go one covers the same pipeline, with a context on every call and a typed error that errors.As recovers. The TypeScript one covers task creation, retry, status reads and bounded waiting; for uploads and the rest of the surface in Node.js, use the SDK.
Copyable reference clients
Download zero-dependency examples covering model discovery, task creation, failed-task retry, status reads, every terminal state, bounded waiting, idempotency and errors. Once accepted, a task cannot be canceled.
These are documentation examples, not published npm, PyPI or Go modules. Ten minutes is a local wait bound, not a production SLA.
