Skip to main content
Spiral serves text models (category = llm) through the request formats existing SDKs speak, on the same API origin and key as every other call: Answers stream when you send "stream": true. Request bodies can be large (long conversations, inline images and documents). Model ids are the ones GET /v1/tools?category=llm lists, such as openai/gpt-4o-mini.

Quickstart

The Anthropic SDKs send the key as x-api-key; that works too. For Claude Code, set ANTHROPIC_BASE_URL to https://api.spiral.ai and ANTHROPIC_AUTH_TOKEN to your key.

Billing

Each call is a run with the same rules as every other: before the model is called, Spiral holds the most the call can cost (the request’s size as input tokens, plus the output cap as output tokens, at the model’s listed rates). A call with an image, audio, video or document also holds what each file can cost on the model’s provider: an image by its size, audio and video by their length, a PDF by its pages. A file whose cost Spiral can’t tell before the call (a video by link, for example) holds the model’s whole input limit instead. You are still charged only what the model used. When the call ends, you are charged what the model actually generated and the hold is released. Your spend caps and balance apply. Without an output cap (max_tokens, max_completion_tokens or max_output_tokens), Spiral sends the model’s default, at most 4,096 tokens. Every answer carries an x-spiral-run-id header: the call’s run, which GET /v1/runs/{id} and the console show with its usage and charge (never your prompt or the answer).

Limits and errors

  • Rate limits are your key’s own; a call counts as one request. A refusal is a 429 with Retry-After.
  • Errors come in the format’s own shape: {"error": {"message", "type", "code"}} for the OpenAI endpoints and {"type": "error", "error": {"type", "message"}} for /v1/messages.
  • Media is accepted as each model’s own provider accepts it, inline (base64) or by link, on all three endpoints:
    • Gemini (google/*): images, PDFs, audio and video, as https:// links, gs:// objects, YouTube links or inline data, in image_url, file, input_audio (Chat), image and document (Messages), or input_image and input_file (Responses).
    • Claude (anthropic/*): images (JPEG, PNG, GIF, WebP) and PDFs, by link or inline, and plain-text files. Claude does not read audio or video: those parts are refused with a 400 naming the field.
    • OpenAI (openai/*): images and documents (PDFs and other files) by link or inline, and audio for its audio models, on all three endpoints. The -pro and -codex models answer on all three endpoints too. On /v1/chat/completions and /v1/messages, a request with a document by link does not take stop sequences (stop, stop_sequences): it is refused with a 400 naming the field.
    • Other models: what their provider accepts.
  • Structured output (response_format, Responses’ text.format, Anthropic’s output_config.format) and reasoning effort (reasoning_effort, reasoning.effort, output_config.effort, thinking) work on every endpoint, for every model that supports them. On Claude, json_object asks for a JSON object; use a JSON schema to enforce one.
  • Each model takes only the request fields its provider documents for it, listed in the model’s input_schema (GET /v1/tools/inspect), with the values each field takes (minimum, maximum, exclusiveMaximum, and maxItems on stop). A field the model does not take, a value outside its range, or two fields the model takes only one of (each marked "x-spiral-excludes": ["<other field>"], such as temperature and top_p on some Claude models) is refused with a 400 naming the field, before anything is charged.
  • A provider’s stored file id (file_id) cannot be read by another provider: send the file inline or by link.
  • Web search plugins (plugins, web_search_options) and server-side tools (a tool whose type is not function) are refused with a 400: they are billed beyond tokens. Function tools work as usual.
  • If you send more than one output cap field, the largest one is used.
  • An optional Idempotency-Key header makes a retry safe: one key starts one call. Resent while that call runs, it answers 409 IDEMPOTENCY_IN_PROGRESS (retry after Retry-After); resent once it finished, it answers 409 GATEWAY_CALL_REPLAYED with the earlier call’s run id (x-spiral-run-id) and its status (run_status: completed, failed or canceled), and nothing is charged again. An answer is never stored, so it cannot be returned twice: to call again after a failed call, send a new key. Without a key, every request is a new call.
  • An optional X-Spiral-End-User-Id header names the end user the call is for, as end_user_id does on POST /v1/runs: 1 to 128 visible ASCII characters. The call’s run carries it, so GET /v1/runs?end_user_id=… lists that user’s calls.
  • Send app attribution headers as on POST /v1/runs to see your LLM usage per app.
  • A key in the customer price view can call these endpoints, streamed and not. Its answers keep the model’s token usage (the counts and their details) but carry no cost: any cost or billing field a provider adds to usage is removed.