Responses API vs Chat Completions: Por Que Migrar
Nesta página
Responses API vs Chat Completions
A API Chat Completions serviu como padrão durante anos e grande parte do código que encontra online ainda a utiliza. No entanto, desde 2025, a OpenAI classificou-a como legada e recomenda a Responses API para todos os novos projetos. Esta lição compara as duas interfaces, focando-se nas diferenças que impactam realmente o seu código.
Mudanças Fundamentais
Com a Chat Completions, construía uma lista de mensagens e enviava a lista completa em cada chamada. O estado da conversa residia na sua aplicação, nunca no servidor:
from openai import OpenAI
client = OpenAI()
# Modelo antigo — Chat Completions (legado)
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"},
]
)
print(response.choices[0].message.content)
# Resultado: "The capital of France is Paris."
A Responses API reduz esta mesma chamada a dois parâmetros e fornece acesso direto ao texto gerado. A mensagem de sistema torna-se no parâmetro instructions e extrair o conteúdo já não exige navegar por choices[0].message.content:
from openai import OpenAI
client = OpenAI()
# Novo modelo — Responses API
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the capital of France?"
)
print(response.output_text)
# Resultado: "The capital of France is Paris."
Gestão de Sessão no Lado do Servidor
Esta é a vantagem mais imediata. A API mantém o estado da conversa, pelo que só precisa de referenciar a resposta anterior através do seu ID. Imagine um assistente de suporte: na décima interação, a abordagem Chat Completions obrigava-o a reenviar as nove trocas anteriores, significando que pagava novamente por esses tokens. Aqui, um único campo é suficiente:
# Primeira pergunta
response = client.responses.create(
model="gpt-5.6-terra",
input="My name is Marie."
)
# Segunda pergunta — o contexto é preservado automaticamente
followup = client.responses.create(
model="gpt-5.6-terra",
input="What is my name?",
previous_response_id=response.id
)
print(followup.output_text)
# Resultado: "Your name is Marie."
JSON Garantido, Não JSON Esperançoso
A segunda grande melhoria diz respeito à saída estruturada. Descreve o formato esperado e a Responses API garante que a resposta adere ao seu esquema JSON — permitindo-lhe fazer a desserialização sem redes de segurança. Um formulário de registo que extrai informação de texto livre deixa de falhar só porque o modelo decide adicionar uma frase introdutória antes do seu JSON:
from pydantic import BaseModel
class City(BaseModel):
name: str
country: str
population: int
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={"format": {"type": "json_schema", "json_schema": {
"name": "city",
"strict": True,
"schema": City.model_json_schema()
}}}
)
print(response.output_text)
# Resultado: {"name": "Paris", "country": "France", "population": 2161000}
Chamada de Funções e Streaming
A declaração de ferramentas segue a mesma lógica de simplificação: o descritor da função é declarado de forma plana em tools e a chamada solicitada pelo modelo aparece diretamente em response.output, sem níveis extra de aninhamento.
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the weather like in Lyon?",
tools=[{
"type": "function",
"name": "get_meteo",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Name of the city"}
},
"required": ["city"]
}
}]
)
# A API devolve diretamente a chamada de função a executar
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}, Arguments: {item.arguments}")
# Resultado: Function: get_meteo, Arguments: {"city": "Lyon"}
O streaming já não devolve um fluxo de fragmentos indiferenciados, mas sim eventos tipados. Filtra por event.type e sabe exatamente o que está a tratar — um fragmento de texto, um argumento de função ou o fim da geração:
stream = client.responses.create(
model="gpt-5.6-terra",
input="Tell a short story.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
Guia Rápido de Migração
| Chat Completions | Responses API |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages=[...] | input="..." ou input=[...] |
response.choices[0].message.content | response.output_text |
| Histórico manual | previous_response_id |
response_format | text={"format": {...}} |
tools + tool_choice | tools (simplificado) |
Deve Migrar Imediatamente?
A API Chat Completions permanece funcional e não será removida. Código existente que funciona, não requer alterações e depende de um pipeline de testes construído em torno do formato antigo não ganha nada com uma reescrita urgente. Da mesma forma, se depender de uma biblioteca de terceiros que ainda não suporta a Responses API, aguarde pela sua atualização. No entanto, para qualquer novo projeto, a resposta é clara: a Responses API é o ponto de partida e o restante deste curso procede dessa premissa.
Pontos-chave
- A Responses API substitui a Chat Completions com uma interface mais simples
- A gestão de sessão no lado do servidor elimina a necessidade de reenviar o histórico
- A Saída Estruturada e a chamada de funções estão nativamente integradas
- A migração é direta: os conceitos permanecem iguais, apenas a sintaxe muda