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 — instructions 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.io/v1/responses

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	✅	Identificador do modelo, ex: `openai/gpt-6.1-sol`
`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 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

cURL

Terminal


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

Python

responses.py


from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.ofox.io/v1",
    api_key="<Sua OFOXAI_API_KEY>"
)
 
response = client.responses.create(
    model="openai/gpt-6.1-sol",
    input="Explique o que é um API Gateway",
    instructions="Você é um assistente técnico útil, responda em português.",
    max_output_tokens=1024
)
 
print(response.output_text)

TypeScript

responses.ts


import OpenAI from 'openai'
 
const client = new OpenAI({
  baseURL: 'https://api.ofox.io/v1',
  apiKey: '<Sua OFOXAI_API_KEY>'
})
 
const response = await client.responses.create({
  model: 'openai/gpt-6.1-sol',
  input: 'Explique o que é um API Gateway',
  instructions: 'Você é um assistente técnico útil, responda em português.',
  max_output_tokens: 1024
})
 
console.log(response.output_text)

Formato da resposta


{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1703123456,
  "model": "openai/gpt-6.1-sol",
  "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

multi_turn.py


response = client.responses.create(
    model="openai/gpt-6.1-sol",
    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.py


stream = client.responses.create(
    model="openai/gpt-6.1-sol",
    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

tools.py


response = client.responses.create(
    model="openai/gpt-6.1-sol",
    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-6.1-sol",
    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.