# LLM capabilities and prepaid quotes

All LLM routes accept POST requests at `/api/llm/{model}`. Read `/api/services/llm-{model}` for the exact supported parameters, modalities, token limits, and pricing policy. Unsupported parameters or input modalities return 400 before payment.

New routes:

| Route | Input | Features |
| --- | --- | --- |
| `/api/llm/gpt-6-astra` | Text, images, native PDF | Reasoning, function tools, JSON schemas, SSE |
| `/api/llm/claude-fable-5.1` | Text, images, native PDF | Reasoning, function tools, JSON schemas, SSE |
| `/api/llm/glm-5.3` | Text | Reasoning, function tools, parallel calls, JSON schemas, SSE |
| `/api/llm/glm-5.3-flash` | Text, images, video | Reasoning, function tools, JSON schemas, SSE |

## Quote and payment

POST the **exact generation body** to `/api/llm/{model}/quote` for a free quote. Alternatively, send it to the generation endpoint without payment and read the x402 `PAYMENT-REQUIRED` header. Resend the same body with the quoted payment. Changing messages, tools, media, or output limits can change the amount required.

```json
{
  "messages": [{"role": "user", "content": "Explain x402 in one sentence."}],
  "max_completion_tokens": 1024,
  "reasoning": {"effort": "low"}
}
```

Prices shown on the landing page and in discovery are **starting prices**, not flat prices. The quote reserves a conservative input budget plus the full output budget (including reasoning). Text budgets include UTF-8 and message/schema overhead. Media URLs and encoded media can expand unpredictably, so requests containing media reserve the model's full supported context. This can make a media quote substantially more expensive than a short text quote. Review the quote before paying.

The quoted charge is `ceil_USD_micro((upstream_cost_bound × 1.06 + $0.001) / 0.70)`. This targets at least a 30% gross margin against the configured cost allowance, including a 6% provider-funding allowance and $0.001 operating reserve. It is not a guarantee of company-wide net profit. Customer blockchain transaction fees are separate. Provider price ceilings prevent routing to a more expensive provider; higher context tiers and cache-write rates are included in the bound. Missing verified pricing pauses a route with 503. Quotes are computed on each request; a quote is not a stored reservation and can change after a catalog release.

**LLM payments settle before generation**, on Base, Solana, and MegaETH. There is no automatic refund after settlement, including an upstream failure, timeout, or client disconnect. Do not automatically retry paid requests: a retry is a new purchase. The gateway makes only one upstream generation attempt. `X-LLM-Price` exposes the quoted price. Non-streaming responses also include a `pricing` object.

## Streaming

Set `"stream": true`. After settlement, the response is live `text/event-stream` in OpenAI-compatible SSE format, including reasoning/tool-call deltas, usage when returned upstream, and `[DONE]`. `PAYMENT-RESPONSE` is sent in the response headers. Disconnecting cancels the upstream fetch; the overall request limit is ten minutes.

## Functions and tool results

```json
{
  "messages": [{"role": "user", "content": "Look up the weather in Paris."}],
  "tools": [{"type": "function", "function": {
    "name": "get_weather", "description": "Fetch weather for a city",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
  }}],
  "max_tokens": 2048
}
```

Read `choices[0].message.tool_calls`, execute the function in your application, then send the assistant message and the result in a **new paid request**:

```json
{
  "messages": [
    {"role": "user", "content": "Look up the weather in Paris."},
    {"role": "assistant", "content": null, "tool_calls": [{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}}]},
    {"role": "tool", "tool_call_id": "call_1", "content": "18 C, clear"}
  ],
  "max_tokens": 2048
}
```

Preserve `reasoning_details` and annotations in returned assistant messages when continuing a reasoning conversation. `tool_choice` and `parallel_tool_calls` are available only when the model advertises them. Tools are client-executed functions. Provider-hosted web search, computer execution, image generation, and arbitrary plugins are separate services and are not executed by these chat routes.

## Images, PDFs, video, and audio

Use content arrays rather than a string, according to the model's `inputModalities`:

```json
{
  "messages": [{"role": "user", "content": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
  ]}],
  "max_tokens": 2048
}
```

- Images: `{"type":"image_url","image_url":{"url":"https://..."}}` or an image data URL.
- PDFs: `{"type":"file","file":{"filename":"report.pdf","file_data":"https://..."}}` or an `application/pdf` data URL. Native PDF processing is selected automatically; paid OCR fallback is disabled.
- Video: `{"type":"video_url","video_url":{"url":"https://..."}}` or a video data URL. URL support also depends on the upstream provider.
- Audio, for existing audio-input models: `{"type":"input_audio","input_audio":{"data":"BASE64","format":"wav"}}` (`mp3` also accepted).

The gateway accepts up to 20 MiB per JSON body, 100 messages, and 100 content parts per message. Provider limits may be lower. Model output is text; image/audio generation remain separate endpoints.

## Reasoning and structured output

Use either `reasoning: {effort: "low"}` or `reasoning_effort: "low"`, not both. Supported effort values are model-specific. Where supported, an explicit `reasoning.max_tokens` budget must be below the total output budget. Mandatory-reasoning models cannot disable reasoning. `max_tokens` and `max_completion_tokens` are interchangeable total output budget fields; provide only one. Defaults are 16,384 for reasoning models and 1,024 otherwise, capped by the model maximum.

```json
{
  "messages": [{"role": "user", "content": "Return a short greeting."}],
  "response_format": {"type": "json_schema", "json_schema": {
    "name": "greeting", "strict": true,
    "schema": {"type": "object", "properties": {"greeting": {"type": "string"}}, "required": ["greeting"], "additionalProperties": false}
  }},
  "max_tokens": 2048
}
```

Sampling controls, stop sequences, seed, logprobs, logit bias, and verbosity pass through when advertised by the selected model. Model, provider routing, output count, and paid plugins cannot be overridden by a caller. Full upstream response fields are preserved, including `choices`, `usage`, reasoning details, annotations, tool calls, and finish reasons. The legacy top-level `content` field remains available.