---
title: "Chat"
subtitle: "Text, reasoning, images, documents, and audio with chat models from any provider."
---

Chat models answer messages that can carry text, images, documents, and audio. Send them in any chat format, such as `https://gateway.respan.ai/v1/chat/completions`, and the gateway translates the request for whichever provider serves the model. See [All API formats](/docs/ai-gateway/requests/endpoints).

## Quickstart

<Tabs>
<Tab title="cURL">
```bash
curl https://gateway.respan.ai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Write a haiku about latency."}]}'
```
</Tab>
<Tab title="Python">
```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://gateway.respan.ai", api_key=os.environ["RESPAN_API_KEY"])

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku about latency."}],
)
print(response.choices[0].message.content)
```
</Tab>
<Tab title="TypeScript">
```typescript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gateway.respan.ai", apiKey: process.env.RESPAN_API_KEY });

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Write a haiku about latency." }],
});
console.log(response.choices[0].message.content);
```
</Tab>
</Tabs>

Fields, streaming, structured outputs, and tool calling are on the format pages, such as [Chat Completions](/docs/ai-gateway/requests/chat-completions). Respan parameters work as on any request: see [Respan parameters](/docs/ai-gateway/customers/respan-params).

## Models and providers

Every chat model in the catalog works, from any provider, in any chat format: change `model` to switch. The OpenAI SDK can call a Claude or Gemini model, and the Anthropic SDK can call a GPT model. To pin one provider, prefix the model ID, as in `azure/gpt-5.5`. See [Providers](/docs/ai-gateway/models/overview#providers).

Not every model reads every input. Each model in the [model catalog](https://www.respan.ai/models) lists what it accepts in `input_modalities` (`text`, `image`, `audio`, `video`, `file`), so filter on `image` for vision or `file` for documents.

When a request carries a field the target provider has no equivalent for, the gateway answers `400` and names the field instead of dropping it.

## Reasoning

`reasoning_effort` is mapped across providers where the target has an equivalent:

| OpenAI Chat | Anthropic | Gemini |
| --- | --- | --- |
| `reasoning_effort: "none"` | thinking disabled | `thinkingBudget: 0` |
| `reasoning_effort` minimal to high | `output_config.effort` | `thinkingLevel` |

A token budget can't be expressed in Chat Completions. To set one, use [Anthropic Messages](/docs/ai-gateway/requests/anthropic-messages) with `thinking.budget_tokens`.

## Images and files

Add images and documents as content parts in a user message, in OpenAI's format. The gateway maps them to Anthropic image and document blocks and to Gemini inline data, so one request works for all three.

```python
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the total on this receipt?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
        ],
    }],
)
```

| Part | Takes | Notes |
| --- | --- | --- |
| `image_url` | A public URL or a base64 data URL (`data:image/png;base64,...`) | Add more parts for more images. |
| `file` | A base64 data URL in `file_data`, `application/pdf` or `text/plain` | `filename` is optional. A provider's own `file_id` works only on that provider. |

Base64 makes the body about a third larger than the file, so prefer URLs for large images.

{/* REVIEW: confirm gateway-next drops a route's attempts whose model can't read the request's media (the old gateway did). */}

## Audio

Audio chat models, such as `gpt-audio` and `gpt-audio-mini`, take audio in a message and can answer in audio. Send an `input_audio` part (base64 only), and ask for a spoken answer with `modalities` and `audio`:

```python
response = client.chat.completions.create(
    model="gpt-audio",
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "wav"},
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Answer the question in this recording."},
            {"type": "input_audio", "input_audio": {"data": audio_base64, "format": "wav"}},
        ],
    }],
)
print(response.choices[0].message.audio.transcript)
```

The spoken answer is in `choices[0].message.audio.data` (base64). To turn text into speech or speech into text without a chat model, see [Audio](/docs/ai-gateway/modalities/audio).

{/* REVIEW: confirm which audio chat models beyond OpenAI's are served, and what a request with input_audio returns when routed to a model without audio input. */}

## Pricing and logs

- Each request is one trace. Its root is a `chat` row, named by the `X-Respan-Log-Id` response header, with the messages (media parts included), the reply, tokens, latency, and cost.
- On Respan's credits, a call is charged from the provider's usage report at the model's catalog price. Images, documents, and audio are billed as input tokens. See [Credits vs BYOK](/docs/ai-gateway/spend/credits-vs-byok).
- On your own provider key, the provider bills you, and the call is still logged and counted against your limits.
- A streamed answer that reports no usage is charged its prompt and what it streamed.