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

GET e DELETE: Gestão de Respostas

Aula 7 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Para Além da Criação
  2. GET /v1/responses/{id}
  3. DELETE /v1/responses/{id}
  4. Boas Práticas
  5. Pontos-chave

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_id na 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_id entre as suas respostas

Pontos-chave

  • GET /v1/responses/{id} recupera uma resposta com todo o seu conteúdo e metadados
  • DELETE /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_id na sua própria base de dados para rastreabilidade