Devolución de llamada al completar la tarea (Webhook)

Al enviar tareas de generación asíncrona como video / imagen / audio, puedes incluir una URL de devolución de llamada. Una vez que la tarea finaliza (con éxito o error), enviaremos activamente el resultado por POST a tu URL, para que no tengas que estar consultando constantemente. En las tareas de generación de video e imagen, también puedes usar language para elegir el idioma del mensaje de error.

Inicio rápido

Al enviar una tarea, añade webhook en el nivel superior del cuerpo de la solicitud. Para traducir los mensajes de error, añade también language:

curl -X POST https://tu-dominio-de-acceso/v1/images/generations \
  -H "Authorization: Bearer TU_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": "es"
  }'

Cuando la tarea termine, enviaremos una solicitud POST a tu URL + /callback.

Otros endpoints de tareas asíncronas (video, audio, etc.) usan webhook de la misma forma. Actualmente, language se aplica a POST /v1/videos/generations y POST /v1/images/generations; ambos campos deben estar en el nivel superior del cuerpo de la solicitud.

Elegir el idioma del mensaje de error

language es un parámetro de cadena opcional que solo afecta a error.message en las devoluciones de llamada fallidas. El ID de la tarea, el estado, el progreso, el coste y las URL de resultados no cambian según el idioma. Si se omite, se devuelve el mensaje de error original del proveedor upstream o de la plataforma.

Idioma	Valor	Idioma	Valor
Inglés	`en`	Ruso	`ru`
Chino simplificado	`zh`	Francés	`fr`
Japonés	`ja`	Alemán	`de`
Coreano	`ko`	Indonesio	`id`
Portugués	`pt`	Español	`es`

Los valores no distinguen entre mayúsculas y minúsculas, y los espacios iniciales y finales se eliminan automáticamente. Por ejemplo, "ES" y " es " se tratan como es.
Usa los códigos de dos letras de la tabla. Las etiquetas regionales como zh-CN, en-US y pt-BR no se reconocen.
Un valor no admitido no hace que falle el envío de la tarea; la devolución de llamada conserva el mensaje de error original.
Si el mensaje original ya está en el idioma de destino, se devuelve sin volver a traducirlo.
Si la traducción falla, se devuelve el mensaje original sin retrasar ni descartar la devolución de llamada.

Durante el sondeo, usa el parámetro de consulta language del endpoint de estado de la tarea para elegir el mismo idioma del mensaje de error. Un Webhook no tiene cadena de consulta, por lo que language debe especificarse al enviar la tarea.

POST /mj/submit/* y POST /v1/images/edits no admiten webhook / language. Los modelos de imagen oficiales de xAI no admiten language y devuelven 400 parameter "language" is not supported si se incluye este parámetro. No envíes este parámetro a esos modelos.

Reglas de la URL

El webhook que proporcionas es la URL base, a la que añadimos automáticamente /callback:

Tu `webhook`	A dónde enviamos realmente el 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`

Por lo tanto, tu servidor necesita un endpoint que acepte POST .../callback.

Qué vas a recibir

El contenido enviado es exactamente igual al que devuelve el endpoint «Obtener estado de la tarea»: puedes procesarlo con la misma lógica de análisis.

{
  "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": "No se puede acceder a la imagen de entrada. Comprueba que la URL sea accesible públicamente",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

Para tareas de video el resultado está en result.videos, y para audio en result.audios.

El ejemplo de error anterior usa "language": "es". El parámetro de idioma solo cambia error.message; los demás campos permanecen iguales.

Solo enviamos cuando una tarea alcanza un estado final (completed / failed); no enviamos mientras está en procesamiento.

Reintentos y deduplicación (importante)

Reintentos: Si tu servidor no devuelve 2xx en unos 10 segundos, o devuelve 5xx, reintentaremos automáticamente, hasta 3 veces, con intervalos de aproximadamente 10 s, 30 s y 60 s. Si las 3 fallan, desistimos (en unos 2 minutos).
Sin reintento: Si tu endpoint devuelve 4xx (se considera URL / solicitud incorrecta), desistimos de inmediato sin reintentar.
Deduplicación: Normalmente una tarea se envía solo una vez. Pero en casos extremos (p. ej., un reinicio de nuestro lado tras el envío pero antes de la confirmación) podrías recibir envíos duplicados. Asegúrate de deduplicar de forma idempotente por id (task_id) para evitar el procesamiento doble.

Recomendaciones para tu endpoint receptor:

Devuelve 2xx lo antes posible

Recibe y encola primero, luego procesa de forma asíncrona; no nos hagas esperar a que termines de procesar.

Deduplica por id

Usa id (task_id) como clave de idempotencia para evitar el procesamiento doble.

Configura y verifica la firma

En producción, verifica el origen de las solicitudes de devolución de llamada y rechaza las falsificadas.

Requisitos de la URL de devolución de llamada

Por seguridad, la URL de devolución de llamada debe cumplir:

Requisito	Descripción
Accesible públicamente	No puede ser una dirección interna / local (p. ej. `127.0.0.1`, `10.x`, `192.168.x` serán rechazadas)
Protocolo	`http` o `https` (`https` recomendado)
Puerto	Usa puertos estándar (`80` / `443`); los puertos no estándar pueden bloquearse
Dominio	No puede apuntar a nuestro propio dominio de servicio

Las URL que no cumplan estos requisitos se descartan (sin envío ni reintento).

Preguntas frecuentes

¿Envié una tarea con webhook pero no recibí ningún envío?

Revisa punto por punto:

¿La tarea realmente finalizó? Consulta los detalles de la tarea: ¿status es completed / failed (no se envía durante el procesamiento)?
¿Tu URL es accesible públicamente? ¿Podemos alcanzar tu /callback?
¿El puerto es estándar (80 / 443)? Los puertos no estándar pueden ser bloqueados por las políticas de seguridad.
¿Tu /callback devolvió 2xx a tiempo? Si devuelve 4xx, desistimos de inmediato.
¿Usas https? ¿El certificado es válido?

¿Por qué url en el resultado es un array?

Algunos modelos producen varias imágenes a la vez, por lo que images[].url puede ser un array; simplemente trátalo como un array.

¿Los enlaces de resultado caducan?

Si result incluye expires_at (marca de tiempo Unix), indica la hora de caducidad del enlace; transfiérelo/guárdalo a tiempo.

¿Se envía el estado 'en procesamiento'?

No. Solo enviamos una vez, cuando la tarea finalmente tiene éxito o falla.

Ejemplo 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("Devolución de llamada de tarea recibida:", data["id"], data["status"])
        # TODO: deduplicar por id, verificar la firma y luego procesar
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

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

Devuelve 200 lo antes posible y ejecuta tu lógica de procesamiento de forma asíncrona en segundo plano.

Visión general

Modelos

Serie de texto

Serie de imágenes

Serie de video

Serie de audio

Serie de Moderación

Gestión de subidas

Gestión de tareas

Gestión de cuenta

Devolución de llamada al completar la tarea (Webhook)

Inicio rápido

Elegir el idioma del mensaje de error

Reglas de la URL

Qué vas a recibir

Reintentos y deduplicación (importante)

Requisitos de la URL de devolución de llamada

Preguntas frecuentes

Ejemplo mínimo de receptor

​Inicio rápido

​Elegir el idioma del mensaje de error

​Reglas de la URL

​Qué vas a recibir

​Reintentos y deduplicación (importante)

​Requisitos de la URL de devolución de llamada

​Preguntas frecuentes

​Ejemplo mínimo de receptor

Inicio rápido

Elegir el idioma del mensaje de error

Reglas de la URL

Qué vas a recibir

Reintentos y deduplicación (importante)

Requisitos de la URL de devolución de llamada

Preguntas frecuentes

Ejemplo mínimo de receptor