Webhooks y ciclo de vida del trabajo multimedia

Guía operativa para trabajos multimedia asíncronos: registro de webhooks, estados, consulta periódica, códigos de error, cargos y límites de idempotencia, estrictamente según la implementación actual del código.

1. POST /api/media/generate: cuando tiene éxito, 202 y { ok: true, jobId, status: "processing" }. No hay estados queued / running separados en la API: hasta que finaliza el trabajo, el cliente ve processing.
2. El servicio ascendente puede pasar por etapas internas (waiting, generating); estas no se reflejan en la API pública. Mientras haces sondeos, el trabajo permanece en processing.
3. Estados de Terminal: success (tiene resultUrls, se cobra si tiene éxito) o fail (sin cargo).
4. La finalización se registra una sola vez: mediante la devolución de llamada del upstream o en una consulta diferida en GET /api/media/jobs/{id}.

# 2. poll the job until it is ready
curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultUrls":["https://..."],"priceRub":...}

Una URL por cuenta: mediaWebhookUrl. Se configura en dashboard → Webhooks o mediante la API con una sesión de cuenta (una cookie después de iniciar sesión). El endpoint no acepta sk-pv-…; solo una sesión autenticada.

# Example (a dashboard session is required, not an API key)
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":"https://example.com/webhooks/media"}'

# Clear the URL
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":null}'

Cuando un trabajo alcanza un estado terminal, GetVibe crea un evento lógico y lo entrega mediante POST al mediaWebhookUrl registrado. La entrega está limitada: el servicio realiza un máximo de 5 intentos en total. El mismo contenido puede llegar más de una vez.

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

• Se cobra una sola vez cuando tiene éxito. En finalizeJob, la transición processing → success|fail es atómica: un callback o una consulta repetidos no generan un segundo cobro.
• fail — gratis. No se realiza ningún débito con un estado fail.
• Cuota de admisión. Si se guardó una cuota al crearla, se cobra exactamente esa cantidad cuando la operación se completa correctamente (nunca más que la medición real del proveedor ascendente).
• Crea la idempotencia mediante un header. Un POST repetido a /api/media/generate sin el header crea un nuevo trabajo y genera un nuevo cobro cuando tiene éxito. Envía Idempotency-Key (hasta 255 caracteres ASCII): un reintento con la misma clave y el mismo cuerpo durante 24 horas devuelve el mismo jobId sin crear un nuevo trabajo; la misma clave con un cuerpo diferente devuelve 422, y 409 mientras la primera solicitud siga procesándose. El jobId de una generación pagada también aparece en GET /v1/generations (el campo job_id).
• El webhook está limitado a cinco intentos. Se crea un evento lógico por cada transición terminal, pero los intentos de entrega pueden repetirse. Después de cinco fallos, el evento recibe el estado FAILED. El controlador del cliente debe deduplicar el par jobId + status.