Códigos de error de la API de vídeo con IA: qué significan y cuándo reintentar

Dos lugares donde puede aparecer un error

Un trabajo de vídeo o imagen puede fallar en dos momentos, y tu código tiene que gestionar ambos:

1. Al enviarlo. POST /v1/generations responde con un estado de error HTTP y un cuerpo como {"error": {"code": "...", "message": "..."}}. No se inició nada y no se cobra nada.
2. Mientras se ejecuta. El envío funcionó y devolvió 202, pero el trabajo termina después con status: "failed". Su error incluye un code, un message que puedes mostrar a quien lo pidió, y retryable.

Un trabajo fallido nunca se cobra, con ningún modelo. El precio se retiene de tu saldo al enviar y se libera si el trabajo falla.

Errores HTTP al enviar

La regla general: vale la pena reintentar 429, 500 y 503 con espera progresiva; cualquier error del rango 4xx salvo 429 significa que hay que cambiar la solicitud en sí.

Por qué falla un trabajo después de empezar

Entre bambalinas, cuando un trabajo llega a una ruta saturada o averiada, pasa por sí solo a la siguiente, así que cuando ves model_busy o all_routes_failed ya se probaron todas las rutas. El campo attempts indica cuántas. Esperar uno o dos minutos antes de volver a intentarlo suele bastar.

Rechazos por contenido

content_policy es el fallo más frecuente. Lo decide el modelo, no la API, y el reason indica qué regla se activó. Las causas habituales son el nombre o el rostro de una persona famosa en el prompt o en una imagen de referencia (real_person), marcas y personajes conocidos (copyright) y cualquier cosa que parezca implicar a un menor. Reintentar la misma solicitud no sirve: reformula el prompt o cambia la imagen. Los modelos difieren en su nivel de rigor, así que el mismo prompt puede pasar en uno y ser rechazado en otro.

Un bucle de reintentos que hace lo correcto

Este helper de Python reintenta lo que vale la pena y se detiene ante lo que no. Importan dos detalles:

• Reenviar un envío tras un 503 o una conexión caída usa la misma Idempotency-Key, así que nunca puede iniciar un segundo trabajo de pago.
• Volver a intentarlo cuando un trabajo falló usa una clave nueva. La misma clave solo devolvería el trabajo fallido.

import os
import time
import uuid

import requests

API = "https://api.revana.si/v1"
AUTH = {"Authorization": f"Bearer {os.environ['REVANA_API_KEY']}"}
RETRY_HTTP = {429, 500, 503}


class GenerationError(Exception):
    pass


def submit(body):
    """POST a job. Retries 429, 500 and 503 with the same Idempotency-Key, so a retry never starts a second job."""
    headers = {**AUTH, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(6):
        r = requests.post(f"{API}/generations", headers=headers, json=body, timeout=60)
        if r.ok:
            return r.json()
        if r.status_code in RETRY_HTTP:
            time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))
            continue
        err = r.json()["error"]  # 400, 401, 402, 403, 409, 413, 422: fix the request, do not retry
        raise GenerationError(f"{r.status_code} {err['code']}: {err['message']}")
    raise GenerationError("still busy after 6 tries")


def wait(job):
    while job["status"] in ("queued", "running"):
        time.sleep(5)
        job = requests.get(f"{API}/generations/{job['id']}", headers=AUTH).json()
    return job


def generate(body, tries=3):
    for n in range(tries):
        job = wait(submit(body))  # each call uses a new key: a failed job is final
        if job["status"] == "succeeded":
            return job
        err = job["error"]
        if not err["retryable"]:
            raise GenerationError(f"{err['code']}: {err['message']}")
        time.sleep(60 * (n + 1))  # model_busy, timeout and the like: wait, then try again
    raise GenerationError(f"gave up after {tries} tries: {err['code']}")


job = generate({
    "model": "seedance-2.0-fast",
    "input": {"prompt": "Waves roll onto black sand at sunset.", "resolution": "480p", "duration": 5},
    "max_cost_usd": 0.3,
})
print(job["output"]["urls"][0], job["cost_usd"])

El trabajo de ejemplo es un clip de Seedance 2.0 Fast de 5 segundos en 480p, que cuesta $0.25 si termina bien y nada si falla. El límite max_cost_usd evita que un ajuste equivocado cueste más de lo esperado.

Cómo evitar errores desde el principio

• Lee las opciones antes de enviar. GET /v1/models y la página de modelos enumeran los tamaños, las duraciones y los límites de referencias de cada modelo. Un valor fuera de ellos se rechaza al instante con 422 invalid_input.
• Sube los archivos en lugar de incrustarlos. POST /v1/uploads acepta imágenes de hasta 30 MB, clips de hasta 50 MB y audio de hasta 15 MB, y devuelve un enlace válido durante 14 días, lo que mantiene pequeño el cuerpo de la solicitud.
• Comprueba tu saldo desde el código. GET /v1/balance antes de un lote grande te ahorra una racha de errores 402. Los paquetes de créditos están en la página de precios.

Para reducir lo que cuestan los trabajos que sí terminan, consulta cómo reducir los costes de la API de vídeo con IA. La referencia completa de errores está en la documentación; obtén una clave de API para probarlo.