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
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
429withRetry-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, ashttps://links,gs://objects, YouTube links or inline data, inimage_url,file,input_audio(Chat),imageanddocument(Messages), orinput_imageandinput_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 a400naming 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/completionsand/v1/messages, a request with a document by link does not take stop sequences (stop,stop_sequences): it is refused with a400naming the field. - Other models: what their provider accepts.
- Gemini (
- Structured output (
response_format, Responses’text.format, Anthropic’soutput_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_objectasks 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, andmaxItemsonstop). 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 astemperatureandtop_pon some Claude models) is refused with a400naming 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 whosetypeis notfunction) are refused with a400: 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-Keyheader makes a retry safe: one key starts one call. Resent while that call runs, it answers409 IDEMPOTENCY_IN_PROGRESS(retry afterRetry-After); resent once it finished, it answers409 GATEWAY_CALL_REPLAYEDwith the earlier call’s run id (x-spiral-run-id) and its status (run_status:completed,failedorcanceled), and nothing is charged again. An answer is never stored, so it cannot be returned twice: to call again after afailedcall, send a new key. Without a key, every request is a new call. - An optional
X-Spiral-End-User-Idheader names the end user the call is for, asend_user_iddoes onPOST /v1/runs: 1 to 128 visible ASCII characters. The call’s run carries it, soGET /v1/runs?end_user_id=…lists that user’s calls. - Send app attribution headers as on
POST /v1/runsto 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
usageis removed.