> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM APIs

> Call text models with the OpenAI and Anthropic SDKs you already use, on the same key and balance.

Spiral serves text models (`category = llm`) through the request formats existing SDKs speak, on the same API origin
and key as every other call:

| Endpoint | Format | SDKs and tools |
| - | - | - |
| `POST /v1/chat/completions` | OpenAI Chat Completions | OpenAI SDKs, the Vercel AI SDK, LangChain, LiteLLM |
| `POST /v1/responses` | OpenAI Responses | OpenAI SDKs, Codex |
| `POST /v1/messages` | Anthropic Messages | Anthropic SDKs, Claude Code |
| `GET /v1/models` | OpenAI model list | Tools that list models before calling one |

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

```python OpenAI (Python) theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://api.spiral.ai/v1", api_key=SPIRAL_API_KEY)
stream = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a haiku about rain."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

```typescript Anthropic (TypeScript) theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ baseURL: "https://api.spiral.ai", apiKey: process.env.SPIRAL_API_KEY });
const message = await client.messages.create({
  model: "openai/gpt-4o-mini",
  max_tokens: 256,
  messages: [{ role: "user", content: "Write a haiku about rain." }],
});
```

```bash curl theme={null}
curl https://api.spiral.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}'
```

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](/docs/concepts/runs.md) 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](/docs/concepts/pricing.md) 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](/docs/concepts/rate-limits.md) 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](/docs/concepts/app-attribution.md) headers as on `POST /v1/runs` to see your LLM usage per app.
* A key in the [customer price view](/docs/concepts/pricing.md#keys-for-your-own-users) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.