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. A repository check keeps it byte-identical to spicy-server/docs/openapi.yaml.
Production API origin
https://api.spicyapi.ai is the only production origin declared by OpenAPI servers[0].url. Every public endpoint is under /api/v1.
Endpoints
| Method | Path | Purpose |
|---|---|---|
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 |
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 |
GET | /api/v1/chat/credit | Read available, held, and total balance |
POST | /api/v1/common/upload-url | Issue a direct image-upload ticket |
POST | /api/v1/common/download-url | Issue a short-lived task-output download URL |
Authentication and envelopes
Every endpoint uses Authorization: Bearer sk-spicy-…. 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.