Quotes and protocol compatibility

Quote an exact request

A quote tells you the price of one exact request before you pay. It is free, creates no task and reserves no funds. You then submit the same request with the quote attached, so it is accepted only at the price you were shown.

The commands below are for a macOS or Linux terminal, with SPICY_API_KEY set as in the Quickstart. MODEL_ID_FROM_CATALOG is a placeholder: use a model value from your live catalog (GET /api/v1/models), and take every input field from that model's schema.

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # once per new task; reuse it only to resend this same request

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

POST /api/v1/jobs/stream, the native text stream, accepts a quote the same way; see Text and streaming.

Recovering from a lost response

If a submission timed out or the connection dropped, you do not know whether it was accepted. For createTask, retry and POST /v1/videos:

1. Resend the original request with its original Idempotency-Key, using the same API key. You get the original task back, in its current state, and are not charged twice.
2. Do not create another task with a fresh key. A new key means a new generation and a new charge.
3. A replay of an already accepted request stays valid after the quote expires. Expiry gates acceptance, not the task acceptance created.
4. A 409 does not mean "not created". Either the request changed (a new piece of work that needs a new key), or it was sent with a different API key from the same account (resend with the original key). See Idempotency.
5. Read cost and settled from recordInfo for the final charge.

Quotes in the official tools

The CLI and the MCP server quote and ask a person before every billable call, so you do not have to build this step yourself:

• CLI: spicyapi tasks quote prices a request; spicyapi tasks create quotes again, prints the amount and asks before creating. See Costs, confirmation and safety.
• MCP: the assistant can quote freely, but creating a task asks you through your AI client, with the price. See Costs, confirmation and safety.
• SDK: quoteTask returns the quote; pass its quoteId and estimatedCost to createTask or run.

Text and video compatibility

SpicyAPI also speaks the OpenAI, Anthropic and Google Gemini formats for text models, and the OpenAI Videos format for video. The full endpoint list is in the API reference; per-protocol requests, streams and errors are in Text and streaming.

Base URL. The OpenAI format uses https://api.spicyapi.ai/v1. The Anthropic and Google GenAI SDKs append /v1 or /v1beta themselves, so set their base URL to https://api.spicyapi.ai.

Credential. One API key for all of them, in the Authorization: Bearer header. The x-api-key header used by the Anthropic SDK and the x-goog-api-key header used by the Google GenAI SDK are accepted too. A ?key= in the URL never is.

Model. Select an exact model from the live catalog. Whether tools, image messages and generation options work depends on that model's schema, not on the protocol you chose.

Response shape. Each protocol returns its own envelope, not the platform {code, msg, data, request_id} one.

Reasoning fields

Chat models that expose reasoning text may return an optional string in message.reasoning_content, or delta.reasoning_content when streaming. When continuing after a tool call, you can preserve it in the corresponding assistant message where the live model schema supports it.

usage.completion_tokens_details.reasoning_tokens describes the reasoning portion already included in completion_tokens; do not add it again. Not every model returns reasoning text or these token details.

Two shapes worth knowing before you build

• Responses requires the full conversation in input. previous_response_id is unsupported.
• Videos accepts JSON with model, prompt, input_reference, seconds and size, which are mapped to the model's own fields. The returned video id is also a task ID that recordInfo accepts. Its content endpoint redirects with HTTP 302 to a short-lived signed URL.

For a streaming chat example with the official OpenAI, Anthropic and Google clients, see Use an official SDK. The CLI and MCP server submit and track native tasks; they do not stream chat tokens.