Polling y webhooks de PiAPI: procesa el final de las tareas con fiabilidad

Aceptar una solicitud de imagen o vídeo no completa la integración. En las tareas de la API unificada de PiAPI, guarda el identificador, observa el estado final y procesa la salida del modelo. El polling sirve para una primera integración; los webhooks permiten que el backend reaccione al terminar.

1. Guarda el identificador y limita el polling

Tras crear la tarea, guarda data.task_id junto al identificador de tu trabajo. Consulta esa misma tarea con la clave API del servidor. Una respuesta HTTP correcta no demuestra que terminó la generación: revisa data.status.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

Con completed, valida data.output según el modelo; con failed, registra data.error. Limita los reintentos y aumenta los intervalos con variación aleatoria. El plazo de espera de tu aplicación es una decisión local: agotarlo no demuestra que la tarea remota falló o se canceló. Conserva el identificador para reconciliar el estado después.

2. Añade un callback autenticado

Combina el fragmento siguiente con un cuerpo válido de creación de tarea y conserva los campos de configuración existentes. Usa un endpoint HTTPS público y un secreto del almacén seguro del backend. PiAPI documenta que lo envía en la cabecera x-webhook-secret; verifícalo antes de aceptar la notificación.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

El JSON del webhook contiene timestamp y data. Comprueba que la tarea pertenece a tu aplicación, persiste o encola de forma duradera el evento y responde pronto con 2xx. Haz las descargas y el trabajo lento fuera del controlador HTTP. Prevé duplicados: la documentación describe reintentos cuando no recibe una respuesta satisfactoria.

3. Unifica polling y callbacks

Usa un solo controlador de finalización. Una restricción persistente de unicidad sobre el identificador y la acción final evita notificaciones dobles y trabajos posteriores duplicados. Una marca de tiempo sola no identifica eventos entre distintas tareas. Ignora actualizaciones antiguas después del estado final y permite reintentar el worker con seguridad tras una caída.

Si falta el callback o el estado es ambiguo, vuelve a consultar el identificador guardado. Un timeout de consulta no justifica crear a ciegas otra tarea de pago. Distingue los fallos de transporte de un fallo confirmado de la tarea y reconcilia antes de enviarla otra vez.

4. Comprueba los casos de error

Antes de publicar, repite un callback, usa un secreto incorrecto, retrasa la entrega y simula un reinicio del worker. Cada tarea completada debe producir un único resultado duradero; las fallidas deben conservar su error. Sigue después la guía para guardar las salidas.

Referencias: esquema de la API unificada, ejemplo de consulta de tarea y documentación de webhooks. Los ejemplos ilustran la integración; no son una prueba de rendimiento de generación real.