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 nativo —
instructionseinputsã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/responsesParâmetros da requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | string | ✅ | Identificador do modelo, ex: openai/gpt-5.4-mini |
input | string | array | ✅ | Conteúdo de entrada, pode ser uma string de texto puro ou um array de mensagens estruturadas |
instructions | string | — | Instruções do sistema (independentes do input, com Prompt Caching automático) |
stream | boolean | — | Habilitar resposta SSE em streaming, padrão false |
max_output_tokens | number | — | Número máximo de tokens gerados |
temperature | number | — | Temperatura de amostragem 0-2, padrão 1 |
top_p | number | — | Parâmetro de amostragem nucleus |
tools | array | — | Definições de ferramentas disponíveis (Function Calling) |
tool_choice | string | object | — | Estratégia de seleção de ferramenta: auto, none ou ferramenta específica |
truncation | string | — | Estratégia de truncamento: auto truncamento automático / disabled erro ao exceder o limite (padrão) |
text | object | — | Configuração de formato de geração de texto |
store | boolean | — | Se deve armazenar a resposta (padrão true) |
metadata | object | — | Pares chave-valor de metadados personalizados |
provider | object | — | Extensã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 assistenteAo 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
cURL
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
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador único da resposta, começando com resp_ |
object | string | Valor fixo "response" |
created_at | number | Timestamp de criação (Unix em segundos) |
model | string | ID do modelo efetivamente utilizado |
status | string | Status da resposta: completed, failed, in_progress, cancelled |
output | array | Array de itens de saída, incluindo mensagens e chamadas de ferramenta |
usage | object | Estatísticas de uso de tokens |
Entrada com mensagens estruturadas
Use um array de mensagens estruturadas para implementar diálogos multi-turno:
Python
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:
Python
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 evento | Descrição |
|---|---|
response.created | Objeto de resposta criado |
response.output_item.added | Novo item de saída adicionado |
response.content_part.added | Novo fragmento de conteúdo adicionado |
response.output_text.delta | Incremento de texto (saída token a token) |
response.output_item.done | Item de saída concluído |
response.completed | Resposta totalmente concluída |
response.function_call_arguments.delta | Incremento dos argumentos de chamada de função |
response.function_call_arguments.done | Argumentos de chamada de função concluídos |
Function Calling
A Responses API suporta tool calling nativamente:
Python
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
| Valor | Descriçã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ística | Chat Completions | Responses API |
|---|---|---|
| Endpoint | /v1/chat/completions | /v1/responses |
| Formato de entrada | array messages | string input ou array estruturado de itens |
| Instruções do sistema | mensagem com role: "system" | parâmetro instructions (cache independente) |
| Prompt Caching | Instruções do sistema misturadas em messages, prefixo de cache instável | instructions enviado separadamente, com cache automático e maior taxa de acerto |
| Formato de saída | choices[0].message.content | output[0].content[0].text ou output_text |
| Tool call | tool_calls dentro da message | item de saída function_call independente |
| Resultado da ferramenta | mensagem com role: "tool" | item de entrada function_call_output |
| Eventos de streaming | chat.completion.chunk | tipos de eventos estruturados (response.*) |
| Campos de Token | prompt_tokens / completion_tokens | input_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.