Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Chat Completions vs. API Responses: Comparação

Aula 11 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Dois endpoints, duas filosofias
  2. Gestão de estado: a diferença fundamental
  3. Ferramentas e funcionalidades exclusivas
  4. Quando utilizar o Chat Completions?
  5. Quando utilizar a API Responses?
  6. Pontos-chave

Dois endpoints, duas filosofias

A xAI disponibiliza dois endpoints para interagir com os modelos Grok: Chat Completions (/v1/chat/completions) e a API Responses (/v1/responses). Compreender as suas diferenças é essencial para escolher o endpoint adequado ao seu projeto e planear qualquer migração potencial.

Aspeto Chat Completions API Responses
Estado Legado Primário (recomendado)
Gestão de estado Sem estado (enviar histórico) Com estado (previous_response_id)
Armazenamento no servidor Não Sim (30 dias com store: true)
Conversa Vetor de mensagens Encadeada por ID
Ferramentas do servidor Apenas chamada de funções web_search, x_search, code_interpreter, functions
Raciocínio encriptado Não Sim (encrypted_content)
Novas funcionalidades Não prioritárias Prioritárias
Compatibilidade OpenAI Total Parcial

Gestão de estado: a diferença fundamental

Chat Completions: gere o histórico

Em cada pedido, tem de reenviar toda a conversa:

# Chat Completions — reenviar tudo de cada vez
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! How can I help you?"},
        {"role": "user", "content": "What is my first name?"}
    ]
)

API Responses: o servidor gere o histórico

Com a API Responses, um simples identificador basta para continuar uma conversa:

# API Responses — apenas o ID da resposta anterior
response1 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Hello, my name is Alice."
)

response2 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What is my first name?",
    previous_response_id=response1.id
)

O servidor mantém o contexto e reconstrói o histórico automaticamente. Não paga menos tokens (o histórico continua a ser faturado), mas simplifica o seu código e reduz o tamanho dos seus pedidos.

Ferramentas e funcionalidades exclusivas

A API Responses dá acesso a ferramentas do servidor que o Chat Completions não oferece:

  • web_search: pesquisa na web em tempo real
  • x_search: pesquisa em publicações do X (Twitter)
  • code_interpreter: execução de código Python no lado do servidor

Estas ferramentas estão integradas diretamente no pedido:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What is the latest news on AI?",
    tools=[{"type": "web_search"}]
)

O Chat Completions suporta a chamada de funções (ferramentas definidas pelo programador), mas não estas ferramentas do servidor geridas pela xAI.

Quando utilizar o Chat Completions?

O Chat Completions continua a ser a escolha certa em vários cenários:

  • Migração a partir da OpenAI: o seu código existente funciona sem grandes modificações
  • Multi-fornecedor: pretende alternar entre OpenAI, Anthropic e xAI com o mesmo código
  • Frameworks de terceiros: LangChain, LlamaIndex, Haystack e a maioria dos frameworks utilizam o formato Chat Completions
  • Controlo total: deseja gerir o histórico por conta própria (resumo, filtragem, modificação)

Quando utilizar a API Responses?

A API Responses é preferível para:

  • Novos projetos: beneficiar das funcionalidades mais recentes desde o início
  • Ferramentas do servidor: necessidade de pesquisa na web, execução de código ou pesquisa no X
  • Conversas longas: sem necessidade de reenviar o histórico em cada pedido
  • Raciocínio encriptado: acesso ao conteúdo de raciocínio para continuidade entre pedidos

Pontos-chave

  • O Chat Completions é sem estado (gerida o histórico), a API Responses é com estado (o servidor gere)
  • A API Responses oferece ferramentas de servidor exclusivas: web_search, x_search, code_interpreter
  • O Chat Completions tem compatibilidade total com a OpenAI, a API Responses é específica da xAI
  • Ambos os endpoints faturam o histórico completo da conversa
  • Utilize o Chat Completions para compatibilidade, a API Responses para novas funcionalidades