API de Respostas e function_call_output
Nesta página
A API de Respostas: o novo endpoint
A API de Respostas é o novo endpoint principal da xAI, distinto do endpoint de Completions de Chat compatível com a OpenAI. Introduz um formato diferente para chamadas de funções, utilizando o tipo function_call_output para devolver resultados de ferramentas.
Diferenças em relação às Completions de Chat
O endpoint de Completions de Chat (compatível com a OpenAI) utiliza mensagens com a função tool para devolver resultados. A API de Respostas usa um formato diferente, estruturado em torno de tipos de eventos.
Completions de Chat (formato legado)
# Devolver o resultado através de uma mensagem com a função "tool"
messages.append({
"role": "tool",
"tool_call_id": "call_abc123",
"content": {temp: 22, city: Paris}
})
API de Respostas (novo formato)
# Devolver o resultado através de um objeto function_call_output
{
"type": "function_call_output",
"call_id": "call_abc123",
"output": {temp: 22, city: Paris}
}
Principais diferenças:
type: "function_call_output"substituirole: "tool"call_idsubstituitool_call_idoutputsubstituicontent
Utilizar a API de Respostas com o SDK da OpenAI
Pode utilizar o SDK da OpenAI para chamar a API de Respostas da xAI:
from openai import OpenAI
client = OpenAI(
api_key="votre-cle-api",
base_url="https://api.x.ai/v1"
)
# Criar uma resposta com ferramentas
response = client.responses.create(
model="grok-4.5",
input="What's the weather like in Paris?",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}]
)
Note que a API de Respostas utiliza input em vez de messages, e a estrutura das ferramentas é ligeiramente diferente (sem objeto function aninhado).
Gerir a resposta
A resposta da API de Respostas contém um array output com eventos:
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}")
print(f"Arguments: {item.arguments}")
print(f"Call ID: {item.call_id}")
# Executar a função
result = get_weather(city="Paris")
# Continuar a conversa com o resultado
follow_up = client.responses.create(
model="grok-4.5",
input=[
{"type": "function_call_output",
"call_id": item.call_id,
"output": json.dumps(result)}
],
tools=tools,
previous_response_id=response.id
)
O campo previous_response_id
A API de Respostas introduz um mecanismo de encadeamento de conversas através do previous_response_id. Em vez de reenviar todo o histórico de mensagens, basta referenciar a resposta anterior:
# Primeiro pedido
response1 = client.responses.create(
model="grok-4.5",
input="Look up the weather in Paris"
)
# Segundo pedido (encadeado)
response2 = client.responses.create(
model="grok-4.5",
input=[{
"type": "function_call_output",
"call_id": response1.output[0].call_id,
"output": {temp: 22}
}],
previous_response_id=response1.id
)
Isto simplifica a gestão do contexto e reduz o tamanho dos pedidos.
Armazenamento de mensagens no servidor
Com store_messages=True, a xAI armazena as mensagens nos seus servidores:
response = client.responses.create(
model="grok-4.5",
input="User question",
tools=tools,
store_messages=True
)
Combinado com previous_response_id, isto permite manter conversas longas sem reenviar o histórico completo em cada pedido.
Quando utilizar a API de Respostas?
Para um novo projeto construído especificamente para a xAI, a API de Respostas é a escolha padrão, por várias razões cumulativas. As inovações chegam aqui primeiro — as novas funcionalidades são adicionadas à API de Respostas antes de qualquer outro local, por vezes em exclusivo. Certas ferramentas de servidor integradas estão apenas disponíveis através deste canal. E para conversas longas, o encadeamento via previous_response_id é estruturalmente mais eficiente do que reenviar o histórico completo a cada turno: menos tokens transferidos, menos código de gestão de estado da sua parte.
As Completions de Chat mantêm dois casos de uso fortes: código existente escrito para a API da OpenAI, que funciona tal como está ao alterar o URL base, e projetos multi-fornecedor onde a portabilidade tem precedência — nestas situações, a compatibilidade supera as funcionalidades exclusivas.
Pontos-chave
- A API de Respostas utiliza
function_call_outputem vez da funçãotool - Os campos mudam:
call_idem vez detool_call_id,outputem vez decontent previous_response_idpermite encadear conversas sem reenviar o históricostore_messages=Trueativa o armazenamento no lado do servidor- A API de Respostas é o endpoint recomendado para novos projetos xAI
- As Completions de Chat permanecem disponíveis para retrocompatibilidade com a OpenAI