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

# Responses API

> Crie respostas de modelos com ferramentas integradas, estado de conversa no servidor, streaming e entrada multimodal pela Responses API do AI Gateway.

**Casos de uso**

> [accordion] Usar ferramentas integradas no servidor
>
> Use busca na web e outras ferramentas integradas sem orquestração de ferramentas no cliente.

> [accordion] Manter o estado da conversa no servidor
>
> O estado no servidor é mantido entre os turnos por meio de `previous_response_id`, sem reenviar todo o histórico de mensagens.

> [accordion] Enviar entrada multimodal
>
> Passe itens `input_image` e `input_file` em uma única solicitação.

> [accordion] Criar fluxos de trabalho no estilo de agentes
>
> Combine function calling, raciocínio e continuação de ferramentas em loops no estilo de agentes.

***

A **Responses API** é o endpoint `/responses` no estilo da OpenAI no **AI Gateway**, exposto em [`POST /v3/router/responses`](/docs/pt-BR/reference/responses/create-response). Ela implementa a especificação [OpenResponses](https://www.openresponses.org/): uma solicitação contém um `model` e um `input`, e a resposta retorna itens de `output` estruturados junto com o uso de tokens e o custo. O endpoint oferece ferramentas integradas, como busca na web, estado de conversa no servidor, streaming e entrada multimodal. Escolha-o quando esses recursos forem importantes; para um fluxo clássico baseado em mensagens, use [Chat Completions](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md).

> [!NOTE]
>
> Invoque um agente configurado definindo `model` como `agent/<key>`; as ferramentas, knowledge bases e memória do agente são aplicadas automaticamente. Consulte Executar agentes.

> [!NOTE]
>
> Uma **Model Fusion** responde a uma solicitação com um painel de modelos e retorna uma única resposta avaliada: defina `model` como o nome da fusion. Consulte [Model Fusion](/docs/pt-BR/ai-gateway/model-fusion.md).

## Responses vs. Chat Completions

Os dois endpoints compartilham a mesma base URL (`https://router.toqan.ai/eu/v3/router`), a mesma autenticação e os mesmos recursos do **AI Gateway**: [fallbacks](/docs/pt-BR/ai-gateway/features/retries.md#fallbacks), [retries](/docs/pt-BR/ai-gateway/features/retries.md), [cache](/docs/pt-BR/ai-gateway/features/cache.md), [guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md) e [budgets](/docs/pt-BR/ai-gateway/budgets.md). A tabela abaixo lista as diferenças.

| Consideração | Responses API ([`POST /v3/router/responses`](/docs/pt-BR/reference/responses/create-response)) | Chat Completions ([`POST /v3/router/chat/completions`](/docs/pt-BR/reference/chat/create-chat-completion)) |
| - | - | - |
| Ferramentas integradas | Compatível. A busca na web (`web_search`, `web_search_preview`) é exclusiva da Responses | Não compatível |
| Estado da conversa | No servidor: `previous_response_id` continua a partir de uma resposta armazenada (`store` tem padrão `true`) | No cliente: reenvie todo o histórico de mensagens a cada turno |
| Entrada multimodal | Itens de `input`: `input_text`, `input_image`, `input_file` | Conteúdo de `messages`: `text`, `image_url`, `file` |
| Controles de raciocínio | [Objeto `reasoning`](/docs/pt-BR/ai-gateway/features/reasoning) para modelos da OpenAI | `reasoning_effort` (OpenAI) e `thinking` (Anthropic, Google Gemini) |
| Eventos de streaming | `response.output_text.delta` e outros eventos de resposta | `choices[0].delta.content` |
| Formato da saída | Array `output` baseado em itens, com o helper `output_text` | `choices[0].message` |

O function calling funciona nos dois endpoints por meio do array `tools`; consulte [Tool Calling](/docs/pt-BR/ai-gateway/features/tool-calling.md).

## Início rápido

Use o SDK da OpenAI com a base URL do **AI Gateway** e chame `client.responses.create`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the capital of France?"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "What is the capital of France?",
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What is the capital of France?",
)

print(response.output_text)
```

## Estado

As respostas são persistidas no servidor por padrão (`store` tem padrão `true`) e podem ser recuperadas pelo ID (`GET /v3/router/responses/{response_id}`; consulte [Retrieve Response](/docs/pt-BR/reference/responses/retrieve-response.md)). Continue uma conversa passando `previous_response_id` na próxima solicitação; o gateway usa a conversa armazenada em vez de exigir todo o histórico novamente. `previous_response_id` exige `store: true` na resposta original. As respostas armazenadas expiram conforme a janela de retenção do workspace; após a expiração, `previous_response_id` retorna `404` com o código `previous_response_not_found`, e recuperar a resposta pelo ID retorna `404` com o código `not_found`. Consulte Retenção de dados.

> [!NOTE]
>
> Defina `store: false` para não persistir uma resposta. A resposta não poderá ser recuperada depois, e `previous_response_id` não funcionará nas solicitações seguintes.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
# First turn. The response ID is returned as "id" in the response body.
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "My name is Ada and I am writing a book about AI."
  }'

# Continue the conversation from the stored response.
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "previous_response_id": "resp_01KP6DFXWPKZ12AS254R4W6C08",
    "input": "What is the title of my book?"
  }'

# Retrieve the stored response by ID.
curl https://router.toqan.ai/eu/v3/router/responses/resp_01KP6DFXWPKZ12AS254R4W6C08 \
  -H "Authorization: Bearer $TOQAN_API_KEY"
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const first = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "My name is Ada and I am writing a book about AI.",
});

const followUp = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  previous_response_id: first.id,
  input: "What is the title of my book?",
});

const retrieved = await client.responses.retrieve(first.id);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

first = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="My name is Ada and I am writing a book about AI.",
)

follow_up = client.responses.create(
    model="openai/gpt-5.6-sol",
    previous_response_id=first.id,
    input="What is the title of my book?",
)

retrieved = client.responses.retrieve(first.id)
```

## Streaming

Defina `"stream": true` no corpo da solicitação. O servidor responde com um stream de Server-Sent Events no formato da OpenAI Responses: o texto incremental chega como eventos `response.output_text.delta`, e o stream termina com um evento de conclusão que contém o uso final. Consulte [Streaming](/docs/pt-BR/ai-gateway/features/streaming.md) para padrões de tratamento de eventos, retry e erros.

## Telemetria

As respostas bem-sucedidas contêm os ids do OpenTelemetry do turno. O corpo da resposta inclui um objeto `telemetry` de nível superior com os ids de trace e de span da solicitação:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "resp_01KP6GDNJY5B0TT0R35KS23PYV",
  "status": "completed",
  "telemetry": {
    "trace_id": "9f2c1b3a4d5e6f708192a3b4c5d6e7f8",
    "span_id": "1a2b3c4d5e6f7081"
  }
}
```

`trace_id` é o id hexadecimal de 32 caracteres do trace, e `span_id` é o id hexadecimal de 16 caracteres do span da resposta. Os mesmos valores são repetidos nos headers de resposta `x-orq-trace-id` e `x-orq-trace-span-id`, definidos por todos os endpoints do router.

> [!NOTE]
>
> O objeto `telemetry` está presente apenas em chamadas bem-sucedidas. As chamadas com falha não o incluem no corpo da resposta: nesse caso, leia os ids dos headers de resposta `x-orq-trace-id` e `x-orq-trace-span-id`, que também são definidos em respostas de erro.

Durante o streaming, os ids chegam no evento final `response.completed`, dentro de `response.telemetry`; o evento `response.created` não os contém. Leia-os do evento de conclusão ou dos headers da resposta.

Use os ids para correlacionar a chamada com o respectivo [Trace](/docs/pt-BR/ai-studio/observability/traces.md) e em qualquer lugar em que um span precise ser referenciado, como ao [anotar um span](/docs/pt-BR/reference/annotations/annotate-a-span.md) ou [registrar feedback](/docs/pt-BR/reference/feedback/post-v2feedback.md).

## Ferramentas integradas

As ferramentas integradas são executadas no servidor: passe-as no array `tools`, e o gateway as executa durante a geração. A busca na web está disponível apenas pela Responses API, como os tipos de ferramenta `web_search` e `web_search_preview`. Consulte [Busca na web na Responses API](/docs/pt-BR/ai-gateway/features/web-search.md) para campos da ferramenta, mapeamento por provedor e a opção `include`.

As ferramentas de função funcionam nos dois endpoints; consulte [Tool Calling](/docs/pt-BR/ai-gateway/features/tool-calling.md).

## Entrada multimodal

Envie imagens e PDFs junto com texto no array `input` usando itens `input_image` e `input_file`. Consulte [Imagem, PDF e áudio: entradas e geração multimodais](/docs/pt-BR/ai-gateway/features/multimodal.md) para formatos compatíveis e exemplos completos.

## Recursos do AI Gateway

Todos os recursos do **AI Gateway** se aplicam à Responses API. A maioria é configurada por solicitação, por meio de campos do corpo da solicitação; os budgets são configurados no console e se aplicam por escopo.

| Recurso | Como se aplica | Campo da solicitação | Documentação |
| - | - | - | - |
| Fallbacks | Tenta um modelo de fallback quando o principal falha | `fallbacks` | [Retries](/docs/pt-BR/ai-gateway/features/retries.md) |
| Retries | Novas tentativas automáticas em códigos de status configurados | `retry` | [Retries](/docs/pt-BR/ai-gateway/features/retries.md) |
| Cache de respostas | Cache de correspondência exata com controle de TTL | `cache`, `cache_control` | [Cache](/docs/pt-BR/ai-gateway/features/cache.md) |
| Service tiers | Executa uma solicitação em um tier premium ou com desconto do provedor | `service_tier` | [Service Tiers](/docs/pt-BR/ai-gateway/features/service-tiers.md) |
| Compactação de contexto | Resume o histórico mais antigo que um limite em um único item | `context_management` | [Context Compaction](/docs/pt-BR/ai-gateway/features/context-compaction.md) |
| Guardrails | Evaluators de LLM e Python em solicitações e respostas | `guardrails` | [Guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md) |
| Budgets | Limites de gastos por workspace, projeto, identidade, chave de API, provedor ou modelo | — | [Budgets](/docs/pt-BR/ai-gateway/budgets.md) |
| Balanceamento de carga | Distribui solicitações entre modelos | `load_balancer` | [Load Balancing](/docs/pt-BR/ai-gateway/features/load-balancing.md) |
| Plugins | Transformações de redação de PII no texto da solicitação e da resposta | `plugins` | [PII Redaction](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md) |
| Mascaramento de traces | Mascara dados de solicitações e respostas nos traces armazenados | `security` | [Segurança](/docs/pt-BR/ai-gateway/features/security.md) |
| Threads | Agrupa solicitações relacionadas na observabilidade | `thread` | [Thread Management](/docs/pt-BR/ai-gateway/thread-management.md) |

## Veja também

* [Create Response](/docs/pt-BR/reference/responses/create-response.md): referência completa de solicitação e resposta
* [Retrieve Response](/docs/pt-BR/reference/responses/retrieve-response.md): obtenha uma resposta armazenada pelo ID
* [API compatível com a OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md): base URL e todos os endpoints compatíveis
* Executar agentes: invoque um agente configurado pela Responses API
* [Raciocínio](/docs/pt-BR/ai-gateway/features/reasoning.md): esforço de `reasoning` para modelos da OpenAI pela Responses API
* Memory stores: memória persistente entre solicitações com o campo `memory`


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