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

# Any SDK, any model

> How a request in one provider format is served by a model on another, and the headers that say what changed

Every inference route serves every provider. Call a Claude model with the
OpenAI SDK, a Gemini model through `/v1/responses`, or a GPT model with the
Anthropic SDK: Verlon translates your request into the serving provider's API
and its answer back into the format you called with — buffered or streamed.

| You call | Serves models on |
| - | - |
| `POST /v1/chat/completions` (OpenAI) | every provider |
| `POST /v1/responses` (OpenAI Responses) | every provider |
| `POST /v1/messages` (Anthropic) | every provider |
| `POST /v1beta/models/{model}:generateContent` (Gemini) | every provider |

When the model's provider speaks your format, the request passes through as
sent. When it doesn't, nothing is changed silently: every response says what
the gateway did.

## Response headers

| Header | Example | Meaning |
| - | - | - |
| `x-verlon-requested-model` | `claude-haiku-5-5` | The model your request named. |
| `x-verlon-served-model` | `claude-haiku-5-5` | The registry model that served it. |
| `x-verlon-route-reason` | `direct` | `direct` (the model you named served), `gate` (the gate's model served), or `routed:<gate model>` (another model served in its place, such as a fallback). |
| `x-verlon-translated` | `chat->anthropic-messages` | The request crossed from your format to the provider's. |
| `x-verlon-emulated` | `stop,tool_choice` | Features the gateway served itself (below). |
| `x-verlon-dropped` | `seed` | Fields the serving model has no equivalent for, left out. |
| `x-verlon-capabilities-served` | `tools=native,structured_output=native` | What your request needed, and how the served model supports it: `native`, `emulated`, `none` or `unknown`. |

## What the gateway serves itself

Where a provider lacks a feature, or implements it differently, Verlon serves
it and names it in `x-verlon-emulated`.

* **Stop sequences** (`stop`). On models whose provider refuses `stop`, or
  applies it in a way your client can't use — OpenAI's reasoning models,
  xAI's Groks (some return the sequence in the text), Meta's Muse, and
  Fireworks models that meet the sequence inside their reasoning — Verlon sends
  the request without it and cuts the answer at the first sequence itself. A
  Messages client gets `stop_reason: "stop_sequence"` and the matched
  `stop_sequence`. A streamed chat completion without
  `stream_options.include_usage` ends at the cut; the request is still billed
  from the provider's own usage.
* **Forced tool choice** (`tool_choice`). A `tool_choice` naming a tool, or
  `required`, on a model that refuses one: DeepSeek's thinking models serve it
  with thinking off for that request; Anthropic's 5.5 generation and Meta's
  Muse get it best-effort — the named tool only, with an instruction to call
  it. When an Anthropic model still answers without the call, the header says
  `tool_choice(unmet)`.
* **Several choices** (`n`). For a chat-completions client, `n` above 1 on a
  model or endpoint that gives one choice per call is served as `n` parallel
  calls, joined into one response. Each call is billed, so `n` prompts are
  billed, as with a provider's own `n`.
* **Prompt caching** (`prompt_cache`). OpenAI caches the start of a prompt
  on its own; Anthropic caches only where a request asks it to. So a
  chat-completions or Responses request to a Claude model is sent with
  Anthropic's automatic caching on, and a conversation or a repeated system prompt is read back from
  the cache. Anthropic bills the first write of a prompt at 1.25 times the
  input price and each read after it at about a tenth, so a one-off prompt
  costs 25% more on its input, and every later request that repeats it within
  5 minutes costs much less. Prompts below the model's cacheable minimum (512
  to 4,096 tokens, depending on the model) aren't cached and cost nothing
  extra. Cached tokens are reported in `usage.prompt_tokens_details.cached_tokens`
  (chat completions) or `usage.input_tokens_details.cached_tokens` (Responses).
* **One tool call per turn** (`parallel_tool_calls`). `parallel_tool_calls:
  false` (Messages: `disable_parallel_tool_use: true`) on a model or API
  without that switch returns only the answer's first tool call, buffered and
  streamed.
* **Gemini 3 thought signatures** (`thought_signature`). Gemini 3 needs the
  signature it returned on each function call sent back with the next turn. A
  chat-completions client gets it on each tool call as
  `extra_content.google.thought_signature`, where Google's own
  OpenAI-compatible API puts it — send the assistant turn back as you received
  it. A Messages or Responses client has no field for it, so Verlon supplies
  Google's documented placeholder and names it in the header.

## Reasoning and citations across shapes

A model's visible reasoning and its web citations come back in your format,
whichever provider answered, streamed or not.

| Your format | Reasoning | Web citations |
| - | - | - |
| Chat completions | `reasoning_content` on the message (and on stream deltas) | `url_citation` annotations (streamed on the closing chunk) |
| Responses | A `reasoning` item with the summary, when you set `reasoning.summary` | `url_citation` annotations on the `output_text` |
| Anthropic Messages | A `thinking` block, when your request turns thinking on and doesn't set `display: "omitted"` | `web_search_result_location` citations on the text block |
| Gemini | `thought: true` parts, when you set `thinkingConfig.includeThoughts` | `groundingMetadata` on the candidate |

The reasoning is Claude's thinking, Gemini's thought summaries, an OpenAI
reasoning summary, or the `reasoning_content` an open-model host returns. When
your request would show reasoning, Verlon asks the serving model to show it.

A thinking block or reasoning item written from another provider's reasoning
carries a marker of Verlon's own: a `thinking` signature of `verlon:reasoning`,
or a reasoning item id starting `rs_verlon_`. So does a Messages web citation
written from another provider's: its `encrypted_index` starts `vrln-cite-`.
Send them back with the conversation as usual. Verlon takes them out before
the request reaches any provider, because Anthropic and OpenAI accept only
reasoning and citation indexes they issued themselves. They aren't named in
`x-verlon-dropped`.

## Files, audio and tool images across shapes

A file, audio clip or image reaches the serving model in that provider's own
form, whichever SDK sent it:

* **PDFs and documents.** A Messages `document` block reaches a GPT, Grok or
  open model as a file part (`input_file` on the Responses API, `file` on chat
  completions) and a Gemini model as inline data. A document by URL goes by URL
  to the Responses API and Gemini. The chat-completions file part takes a file
  inline only, so a URL document there is named in `x-verlon-dropped`. A
  plain-text document is sent as text, under its title. A chat `file` part
  reaches Gemini as inline data.
* **Audio.** A chat `input_audio` clip reaches Gemini as inline audio. Inline
  wav or mp3 from a Gemini request reaches a chat-completions model as
  `input_audio`.
* **Images a tool returned.** A screenshot inside a Messages `tool_result`
  reaches the Responses API inside the function output, and Gemini right after
  the function response. On chat completions, where a tool message holds text
  only, it follows the tool messages as a labelled user image.

What only one provider has, such as Anthropic's Files API ids or a document's
`context`, is named in `x-verlon-dropped`.

## Served on the Responses API

Some requests one provider's chat-completions endpoint refuses, its Responses
API serves. Verlon sends them there automatically, recorded as
`x-verlon-translated: chat->responses`:

* OpenAI models served only on Responses (gpt-5-pro, gpt-5.3-codex), and
  reasoning models that take function tools only there;
* PDF input on xAI's Groks;
* a strict JSON schema on DeepSeek, which enforces it only on its Responses
  API.

## Dropped fields

A field the serving model has no equivalent for — `seed` on Claude, OpenAI's
`reasoning` items on another provider, `top_k` on a chat-completions provider
— is left out of the request and named in `x-verlon-dropped`. A field a
provider refuses outright, such as a `reasoning_effort` value a model doesn't
take, is dropped and the request sent again. A DeepSeek tool loop whose history
lacks the model's own reasoning is served with thinking off for that turn
(`x-verlon-dropped: thinking`).

## Requests refused up front

A few requests get a `400` (`unsupported_capability`) before any provider call,
because no translation would give you something usable — and only when the
serving provider itself lacks the capability:

* a strict JSON schema the model cannot enforce;
* an input the model cannot read (an image, a PDF, audio);
* tools on a model with no tool calling at all;
* an output modality the model cannot produce;
* inference pinned to a region the model cannot serve in;
* a model whose answer is a song (Lyria) on `/v1/messages` or `/v1/responses`,
  whose formats have no audio output. Call it through `/v1/chat/completions`
  (the song comes back as `message.audio`) or Gemini `:generateContent`.
  Nothing is sent to the provider and nothing is charged.

The error names the capability, so you can pick another model from the
[registry](https://docs.verlon.ai/provider-compatibility/models.md#live-registry), whose `capabilities`
object lists each model's support.

## Batch and files: not served yet

Verlon does not serve batch jobs or file uploads yet. Their paths answer `501`
in the error format your SDK reads, naming the path, so the SDK raises a clear
error instead of a "not found":

| Kind | Paths |
| - | - |
| Batch | `/v1/batches`, `/v1/messages/batches`, `/v1beta/models/{model}:batchGenerateContent`, `:asyncBatchEmbedContent`, `/v1beta/batches`, `/mistral/v1/batch/jobs` |
| Files | `/v1/files`, `/v1beta/files`, `/upload/v1beta/files`, `/mistral/v1/files` |

Until then, send each request on its own route, and send files inline (a base64
file, document or image part). `GET /v1/registry/endpoints` lists which
providers sell batch and files, and which don't, with the provider page each
answer was read from.


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