Callback de Conclusão de Tarefa (Webhook)

Ao enviar tarefas de geração assíncrona como vídeo / imagem / áudio, você pode incluir uma URL de callback. Assim que a tarefa termina (com sucesso ou falha), enviaremos ativamente o resultado via POST para a sua URL, para que você não precise ficar consultando o tempo todo. Para tarefas de geração de vídeo e imagem, você também pode usar language para escolher o idioma da mensagem de falha.

Início rápido

Ao enviar uma tarefa, adicione webhook no nível superior do corpo da requisição. Para traduzir mensagens de falha, adicione também language:

curl -X POST https://seu-dominio-de-acesso/v1/images/generations \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com",
    "language": "pt"
  }'

Depois que a tarefa terminar, enviaremos uma requisição POST para sua URL + /callback.

Outros endpoints de tarefas assíncronas (vídeo, áudio, etc.) usam webhook da mesma forma. language atualmente se aplica a POST /v1/videos/generations e POST /v1/images/generations; ambos os campos devem estar no nível superior do corpo da requisição.

Escolher o idioma da mensagem de erro

language é um parâmetro de string opcional que afeta apenas error.message nos callbacks de falha. ID da tarefa, status, progresso, custo e URLs de resultado não mudam de acordo com o idioma. Se omitido, a mensagem de erro original do provedor upstream ou da plataforma será retornada.

Idioma	Valor	Idioma	Valor
Inglês	`en`	Russo	`ru`
Chinês simplificado	`zh`	Francês	`fr`
Japonês	`ja`	Alemão	`de`
Coreano	`ko`	Indonésio	`id`
Português	`pt`	Espanhol	`es`

Os valores não diferenciam maiúsculas de minúsculas, e os espaços no início e no fim são removidos automaticamente. Por exemplo, "PT" e " pt " são tratados como pt.
Use os códigos de duas letras da tabela. Tags regionais como zh-CN, en-US e pt-BR não são reconhecidas.
Um valor não compatível não faz a submissão da tarefa falhar; o callback mantém a mensagem de erro original.
Se a mensagem original já estiver no idioma de destino, ela será retornada sem uma nova tradução.
Se a tradução falhar, a mensagem original será retornada sem atrasar nem descartar o callback.

Ao fazer polling, use o parâmetro de query language do endpoint de status da tarefa para escolher o mesmo idioma da mensagem de erro. Um Webhook não tem query string, portanto language deve ser especificado ao enviar a tarefa.

POST /mj/submit/* e POST /v1/images/edits não são compatíveis com webhook / language. Os modelos de imagem oficiais da xAI não são compatíveis com language e retornam 400 parameter "language" is not supported quando o parâmetro é incluído. Não envie esse parâmetro para esses modelos.

Regras de URL

O webhook que você fornece é a URL base, à qual anexamos automaticamente /callback:

Seu `webhook`	Para onde realmente enviamos o POST
`https://your-server.com`	`https://your-server.com/callback`
`https://your-server.com/api`	`https://your-server.com/api/callback`
`https://your-server.com/api/`	`https://your-server.com/api/callback`

Portanto, seu servidor precisa de um endpoint que aceite POST .../callback.

O que você vai receber

O conteúdo enviado é exatamente igual ao que o endpoint “Obter status da tarefa” retorna — você pode processá-lo com a mesma lógica de análise.

{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "Não foi possível acessar a imagem de entrada. Verifique se a URL está acessível publicamente",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

Para tarefas de vídeo, o resultado fica em result.videos, e para áudio em result.audios.

O exemplo de falha acima usa "language": "pt". O parâmetro de idioma altera apenas error.message; todos os outros campos permanecem iguais.

Só enviamos quando uma tarefa atinge um estado final (completed / failed); não enviamos enquanto está em processamento.

Novas tentativas e deduplicação (importante)

Novas tentativas: Se o seu servidor não retornar 2xx em cerca de 10 segundos, ou retornar 5xx, tentaremos novamente de forma automática, até 3 vezes, em intervalos de aproximadamente 10s, 30s e 60s. Se as 3 falharem, desistimos (em cerca de 2 minutos).
Sem nova tentativa: Se o seu endpoint retornar 4xx (considerado URL / requisição com problema), desistimos imediatamente, sem tentar de novo.
Deduplicação: Normalmente uma tarefa é enviada apenas uma vez. Mas em casos extremos (ex.: um reinício do nosso lado após o envio, mas antes da confirmação) você pode receber envios duplicados. Certifique-se de deduplicar de forma idempotente por id (task_id) para evitar processamento em duplicidade.

Recomendações para o seu endpoint receptor:

Retorne 2xx o quanto antes

Aceite e enfileire primeiro, depois processe de forma assíncrona — não nos faça esperar até você terminar o processamento.

Deduplique por id

Use id (task_id) como chave de idempotência para evitar processamento em duplicidade.

Configure e verifique a assinatura

Em produção, verifique a origem das requisições de callback e rejeite as falsificadas.

Requisitos para a URL de callback

Por segurança, a URL de callback deve atender a:

Requisito	Descrição
Acessível publicamente	Não pode ser um endereço interno / local (ex.: `127.0.0.1`, `10.x`, `192.168.x` serão rejeitados)
Protocolo	`http` ou `https` (`https` recomendado)
Porta	Use portas padrão (`80` / `443`); portas não padrão podem ser bloqueadas
Domínio	Não pode apontar para o nosso próprio domínio de serviço

URLs que não atendem a esses requisitos são descartadas (sem envio nem nova tentativa).

Perguntas frequentes

Enviei uma tarefa com webhook, mas não recebi nenhum envio?

Verifique item por item:

A tarefa realmente terminou? Consulte os detalhes da tarefa — o status está completed / failed (não há envio durante o processamento)?
Sua URL está acessível publicamente? Conseguimos alcançar o seu /callback?
A porta é padrão (80 / 443)? Portas não padrão podem ser bloqueadas por políticas de segurança.
Seu /callback retornou 2xx a tempo? Retornar 4xx é descartado imediatamente.
Você está usando https? O certificado é válido?

Por que url no result é um array?

Alguns modelos produzem várias imagens de uma vez, então images[].url pode ser um array — basta tratá-lo como um array.

Os links de resultado expiram?

Se result incluir expires_at (timestamp Unix), ele indica a hora de expiração do link — transfira/salve-o a tempo.

Vocês enviam o status 'em processamento'?

Não. Enviamos apenas uma vez, quando a tarefa finalmente tem sucesso ou falha.

Exemplo mínimo de receptor

Python

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("Callback de tarefa recebido:", data["id"], data["status"])
        # TODO: deduplicar por id, verificar a assinatura e então processar
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()

Retorne 200 o quanto antes e execute sua lógica de processamento de forma assíncrona em segundo plano.

Visão Geral

Modelos

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Callback de Conclusão de Tarefa (Webhook)

Início rápido

Escolher o idioma da mensagem de erro

Regras de URL

O que você vai receber

Novas tentativas e deduplicação (importante)

Requisitos para a URL de callback

Perguntas frequentes

Exemplo mínimo de receptor

​Início rápido

​Escolher o idioma da mensagem de erro

​Regras de URL

​O que você vai receber

​Novas tentativas e deduplicação (importante)

​Requisitos para a URL de callback

​Perguntas frequentes

​Exemplo mínimo de receptor

Início rápido

Escolher o idioma da mensagem de erro

Regras de URL

O que você vai receber

Novas tentativas e deduplicação (importante)

Requisitos para a URL de callback

Perguntas frequentes

Exemplo mínimo de receptor