OpenAPI and endpoint index
Downloadable OpenAPI 3.1 contract, every public endpoint, and the production origin.
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 packages. Ten minutes is a local wait bound, not a production SLA.
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.
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. Usage is scoped to the authenticated API key. Key creation, rotation and budget settings remain in the Console.
Model discovery, pricing and account APIs
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/models | Read callable models, account prices, and optional schemas |
GET | /api/v1/models/{model} | Read one model and its complete JSON Schema |
POST | /api/v1/jobs/quote | Quote the exact request for five minutes without creating a task or holding funds |
GET | /api/v1/chat/credit | Read available, held, and total balance |
GET | /api/v1/usage | Read current-key calls and settled USD spending by date and model |
Generation and task APIs
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/jobs | List the current API key's task history with cursor pagination |
POST | /api/v1/jobs/createTask | Create an asynchronous generation task |
GET | /api/v1/jobs/recordInfo | Read a task owned by the caller |
POST | /api/v1/jobs/retry | Create a new task from a failed or expired task; historical canceled records remain compatible |
POST | /api/v1/jobs/stream | Run a text model and stream the answer over SSE |
Media APIs
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/common/upload-url | Issue a direct media-upload ticket |
POST | /api/v1/files/{fileId}/commit | Verify and commit a direct upload, returning the task-ready spicy:// URI |
POST | /api/v1/common/download-url | Issue a short-lived task-output download URL |
Authentication and envelopes
Every endpoint accepts 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. Task API JSON responses share the {code,msg,data,request_id} envelope. A task's outcome is expressed by data.state, not the envelope code.
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 |