GET e DELETE: Gestão de Respostas
Nesta página
Para Além da Criação
A API de Respostas não se limita à criação de respostas. Dois endpoints complementares permitem-lhe recuperar e eliminar respostas armazenadas. Estas operações são essenciais para construir aplicações robustas com gestão de histórico.
GET /v1/responses/{id}
Recuperar uma Resposta
curl https://api.x.ai/v1/responses/resp-abc123def456 \
-H "Authorization: Bearer $XAI_API_KEY"
A API devolve exatamente o mesmo objeto JSON que durante a criação:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [...],
"usage": {...}
}
Casos de Uso Práticos
Retoma de Conversa: A sua aplicação armazena o último response_id na sessão do utilizador. Ao reconectar, recupere a resposta para exibir o contexto anterior.
# O utilizador regressa após uma pausa
last_response_id = get_from_session(user_id)
previous = client.responses.retrieve(last_response_id)
# Exibir a última troca
print(f"Última resposta: {previous.output[0].content[0].text[:200]}...")
# Continuar a conversa
new_response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Onde é que estávamos?",
previous_response_id=last_response_id
)
Auditoria de Custos: Percorra as suas respostas armazenadas para analisar o consumo por utilizador ou funcionalidade.
response = client.responses.retrieve("resp-abc123")
cost_usd = response.usage.cost_in_nano_usd / 1e9
input_tokens = response.usage.input_tokens
output_tokens = response.usage.output_tokens
print(f"Custo: ${cost_usd:.6f} | Entrada: {input_tokens} | Saída: {output_tokens}")
Gestão de Erros
Se a resposta não existir (eliminada ou expirada), a API devolve um erro 404:
{
"error": {
"message": "Response not found",
"type": "not_found_error"
}
}
Trate este caso no seu código:
try:
response = client.responses.retrieve("resp-expired123")
except Exception as e:
print(f"Resposta não encontrada: {e}")
# Iniciar uma nova conversa
DELETE /v1/responses/{id}
Eliminar uma Resposta
curl -X DELETE https://api.x.ai/v1/responses/resp-abc123def456 \
-H "Authorization: Bearer $XAI_API_KEY"
A eliminação devolve um estado 200 em caso de sucesso. A operação é irreversível.
Impacto em Conversas Encadeadas
Quando elimina uma resposta referenciada por outras através de previous_response_id, o contexto dessa resposta desaparece da cadeia. As respostas subsequentes não são eliminadas, mas perdem o acesso ao contexto anterior.
resp-1 → resp-2 → resp-3 → resp-4
↑ eliminada
Se eliminar a resp-2, a resp-3 e a resp-4 continuam a existir, mas o contexto da resp-1 e da resp-2 deixa de estar acessível para novos pedidos encadeados.
Limpeza Automatizada
Para aplicações de produção, implemente uma limpeza periódica:
import datetime
def cleanup_old_responses(response_ids, max_age_days=7):
for rid in response_ids:
try:
resp = client.responses.retrieve(rid)
age = datetime.datetime.now().timestamp() - resp.created_at
if age > max_age_days * 86400:
client.responses.delete(rid)
print(f"Eliminada: {rid}")
except Exception:
pass # Já eliminada ou expirada
Boas Práticas
- Armazene os IDs: mantenha os
response_idna sua base de dados juntamente com os metadados da conversa - Limpe regularmente: não espere pela expiração automática de 30 dias para dados sensíveis
- Trate os erros 404: uma resposta pode desaparecer entre pedidos (expiração, eliminação manual)
- Documente as suas cadeias: para depuração, rastreie as ligações
previous_response_identre as suas respostas
Pontos-chave
GET /v1/responses/{id}recupera uma resposta com todo o seu conteúdo e metadadosDELETE /v1/responses/{id}elimina permanentemente uma resposta — operação irreversível- Eliminar uma resposta intermédia quebra o contexto da cadeia de conversação
- Trate os erros 404: as respostas expiram automaticamente após 30 dias
- Mantenha os
response_idna sua própria base de dados para rastreabilidade