Pular para o conteúdo principal
Casos de uso
Use busca na web e outras ferramentas integradas sem orquestração de ferramentas no cliente.
O estado no servidor é mantido entre os turnos por meio de previous_response_id, sem reenviar todo o histórico de mensagens.
Passe itens input_image e input_file em uma única solicitação.
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. Ela implementa a especificação OpenResponses: 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.
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.
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.

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, retries, cache, guardrails e budgets. A tabela abaixo lista as diferenças. O function calling funciona nos dois endpoints por meio do array tools; consulte Tool Calling.

Início rápido

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

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). 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.
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.

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 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:
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.
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 e em qualquer lugar em que um span precise ser referenciado, como ao anotar um span ou registrar feedback.

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 para campos da ferramenta, mapeamento por provedor e a opção include. As ferramentas de função funcionam nos dois endpoints; consulte Tool Calling.

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 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.

Veja também

  • Create Response: referência completa de solicitação e resposta
  • Retrieve Response: obtenha uma resposta armazenada pelo ID
  • API compatível com a OpenAI: base URL e todos os endpoints compatíveis
  • Executar agentes: invoque um agente configurado pela Responses API
  • Raciocínio: esforço de reasoning para modelos da OpenAI pela Responses API
  • Memory stores: memória persistente entre solicitações com o campo memory