Skip to Content

Responses API (Recomendado)

Crie respostas do modelo. Suporta entrada de texto e imagem, gerando saída de texto ou JSON. Suporta function calling (Tool Calling), resposta em streaming e diálogo multi-turno.

Recomendamos a Responses API para novos projetos. Esta é a nova geração de API lançada pela OpenAI, e em comparação com Chat Completions oferece as seguintes vantagens:

  • Prompt Caching nativoinstructions e input são separados, e as instruções do sistema funcionam automaticamente como prefixo de cache. Em diálogos multi-turno, a parte do prefixo que não muda tem maior taxa de acerto de cache, podendo economizar até 50% do custo de tokens de entrada e reduzir a latência
  • Modelo de item estruturado — Formatos de entrada/saída mais claros, com suporte nativo ao fluxo de tool calling
  • Eventos de streaming mais ricos — Tipos de eventos SSE de granularidade fina, facilitando a renderização de UI em tempo real

Endpoint

POST https://api.ofox.ai/v1/responses

Parâmetros da requisição

ParâmetroTipoObrigatórioDescrição
modelstringIdentificador do modelo, ex: openai/gpt-5.4-mini
inputstring | arrayConteúdo de entrada, pode ser uma string de texto puro ou um array de mensagens estruturadas
instructionsstringInstruções do sistema (independentes do input, com Prompt Caching automático)
streambooleanHabilitar resposta SSE em streaming, padrão false
max_output_tokensnumberNúmero máximo de tokens gerados
temperaturenumberTemperatura de amostragem 0-2, padrão 1
top_pnumberParâmetro de amostragem nucleus
toolsarrayDefinições de ferramentas disponíveis (Function Calling)
tool_choicestring | objectEstratégia de seleção de ferramenta: auto, none ou ferramenta específica
truncationstringEstratégia de truncamento: auto truncamento automático / disabled erro ao exceder o limite (padrão)
textobjectConfiguração de formato de geração de texto
storebooleanSe deve armazenar a resposta (padrão true)
metadataobjectPares chave-valor de metadados personalizados
providerobjectExtensão OfoxAI: configuração de roteamento e failover

Formato do Input

input suporta dois formatos:

1. String simples — passe o texto diretamente

{ "input": "Olá, por favor se apresente" }

2. Array de mensagens estruturadas — diálogo multi-turno e entrada multimodal

interface InputItem { type: 'message' role: 'user' | 'assistant' content: ContentPart[] id?: string // obrigatório em mensagens do assistant status?: 'completed' // obrigatório em mensagens do assistant } type ContentPart = | { type: 'input_text'; text: string } // entrada de texto do usuário | { type: 'input_image'; image_url: string } // entrada de imagem | { type: 'output_text'; text: string; annotations?: any[] } // saída de texto do assistente

Ao incluir mensagens com papel assistant em diálogos multi-turno, os campos id e status são obrigatórios. A Responses API foi projetada como stateless (sem estado), e cada requisição deve carregar o histórico completo da conversa.

Exemplos de requisição

Terminal
curl https://api.ofox.ai/v1/responses \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.4-mini", "input": "Explique o que é um API Gateway", "instructions": "Você é um assistente técnico útil, responda em português.", "max_output_tokens": 1024 }'

Formato da resposta

{ "id": "resp_abc123", "object": "response", "created_at": 1703123456, "model": "openai/gpt-5.4-mini", "status": "completed", "output": [ { "type": "message", "id": "msg_def456", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "Um API Gateway é um...", "annotations": [] } ] } ], "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 } }

Descrição dos campos da resposta

CampoTipoDescrição
idstringIdentificador único da resposta, começando com resp_
objectstringValor fixo "response"
created_atnumberTimestamp de criação (Unix em segundos)
modelstringID do modelo efetivamente utilizado
statusstringStatus da resposta: completed, failed, in_progress, cancelled
outputarrayArray de itens de saída, incluindo mensagens e chamadas de ferramenta
usageobjectEstatísticas de uso de tokens

Entrada com mensagens estruturadas

Use um array de mensagens estruturadas para implementar diálogos multi-turno:

multi_turn.py
response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Qual é a capital da França?"} ] }, { "type": "message", "role": "assistant", "id": "msg_abc123", "status": "completed", "content": [ {"type": "output_text", "text": "A capital da França é Paris.", "annotations": []} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Quantos habitantes ela tem?"} ] } ] ) print(response.output_text)

Resposta em streaming

Defina stream: true para habilitar a resposta SSE em streaming:

stream.py
stream = client.responses.create( model="openai/gpt-5.4-mini", input="Conte uma piada sobre programação", stream=True ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True)

Tipos de eventos de streaming

A resposta em streaming envia os seguintes eventos via SSE:

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}} data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}} data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Olá"} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" mundo"} data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Olá mundo..."}]}} data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}} data: [DONE]
Tipo de eventoDescrição
response.createdObjeto de resposta criado
response.output_item.addedNovo item de saída adicionado
response.content_part.addedNovo fragmento de conteúdo adicionado
response.output_text.deltaIncremento de texto (saída token a token)
response.output_item.doneItem de saída concluído
response.completedResposta totalmente concluída
response.function_call_arguments.deltaIncremento dos argumentos de chamada de função
response.function_call_arguments.doneArgumentos de chamada de função concluídos

Function Calling

A Responses API suporta tool calling nativamente:

tools.py
response = client.responses.create( model="openai/gpt-5.4-mini", input="Como está o tempo em São Paulo hoje?", tools=[ { "type": "function", "name": "get_weather", "description": "Obtém o clima atual de uma cidade específica", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "Nome da cidade, ex: São Paulo" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } ], tool_choice="auto" ) # Processar chamadas de ferramenta for item in response.output: if item.type == "function_call": print(f"Função chamada: {item.name}") print(f"Argumentos: {item.arguments}")

Formato da resposta com tool call

Quando o modelo chama uma ferramenta, output contém um item do tipo function_call:

{ "id": "resp_abc123", "object": "response", "status": "completed", "output": [ { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"São Paulo\",\"unit\":\"celsius\"}" } ], "usage": { "input_tokens": 45, "output_tokens": 25, "total_tokens": 70 } }

Envio do resultado da ferramenta

Para enviar o resultado da execução da ferramenta de volta ao modelo, inclua a cadeia completa de chamadas em input:

# Segunda requisição: envio do resultado da ferramenta response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "Como está o tempo em São Paulo hoje?"}] }, { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"São Paulo\",\"unit\":\"celsius\"}" }, { "type": "function_call_output", "id": "fco_abc123", "call_id": "call_xyz789", "output": "{\"temperature\":\"22°C\",\"condition\":\"ensolarado\"}" } ] ) print(response.output_text) # => "O tempo em São Paulo está ensolarado hoje, com temperatura de 22°C, ótimo para atividades ao ar livre."

Opções de Tool Choice

ValorDescrição
"auto"O modelo decide por si mesmo se chama uma ferramenta (padrão)
"none"Proibido chamar ferramentas
{"type": "function", "name": "tool_name"}Forçar a chamada de uma ferramenta específica

Comparação com Chat Completions

CaracterísticaChat CompletionsResponses API
Endpoint/v1/chat/completions/v1/responses
Formato de entradaarray messagesstring input ou array estruturado de itens
Instruções do sistemamensagem com role: "system"parâmetro instructions (cache independente)
Prompt CachingInstruções do sistema misturadas em messages, prefixo de cache instávelinstructions enviado separadamente, com cache automático e maior taxa de acerto
Formato de saídachoices[0].message.contentoutput[0].content[0].text ou output_text
Tool calltool_calls dentro da messageitem de saída function_call independente
Resultado da ferramentamensagem com role: "tool"item de entrada function_call_output
Eventos de streamingchat.completion.chunktipos de eventos estruturados (response.*)
Campos de Tokenprompt_tokens / completion_tokensinput_tokens / output_tokens

Ambas as APIs podem ser usadas em ambientes de produção. Se você já tem uma integração com Chat Completions, não é necessário migrar. Recomendamos a Responses API para novos projetos, especialmente em cenários com fluxos complexos de tool calling ou chamadas de alta frequência (que aproveitam melhor o cache para reduzir custos). Veja o guia de Function Calling para mais detalhes.

Last updated on