Codes d'erreur de l'API vidéo IA : ce qu'ils signifient et quand réessayer

Deux endroits où une erreur peut apparaître

Une tâche vidéo ou image peut échouer à deux moments, et votre code doit gérer les deux :

1. À l'envoi. POST /v1/generations répond avec un statut d'erreur HTTP et un corps du type {"error": {"code": "...", "message": "..."}}. Rien n'a démarré et rien n'est facturé.
2. Pendant l'exécution. L'envoi a réussi avec 202, mais la tâche se termine ensuite avec status: "failed". Son error contient un code, un message que vous pouvez montrer à la personne à l'origine de la demande, et retryable.

Une tâche en échec n'est jamais facturée, quel que soit le modèle. Le prix est bloqué sur votre solde à l'envoi et libéré si la tâche échoue.

Erreurs HTTP à l'envoi

La règle générale : 429, 500 et 503 valent la peine d'être réessayées avec un délai d'attente croissant ; toute erreur de la plage 4xx autre que 429 signifie que la requête elle-même doit changer.

Pourquoi une tâche échoue après avoir démarré

En coulisses, une tâche qui tombe sur une route saturée ou défaillante passe d'elle-même à la route suivante : lorsque vous voyez model_busy ou all_routes_failed, toutes les routes ont donc déjà été essayées. Le champ attempts indique combien. Attendre une minute ou deux avant de réessayer suffit généralement.

Refus de contenu

content_policy est l'échec que l'on rencontre le plus. C'est le modèle, et non l'API, qui en décide, et reason indique quelle règle s'est déclenchée. Les causes courantes sont le nom ou le visage d'une personne célèbre dans le prompt ou dans une image de référence (real_person), les marques et les personnages connus (copyright), et tout ce qui laisse penser qu'un mineur est concerné. Réessayer la même requête n'y changera rien ; reformulez le prompt ou changez l'image. Les modèles n'ont pas tous la même sévérité : un même prompt peut passer sur l'un et être refusé sur un autre.

Une boucle de nouvelles tentatives qui fait ce qu'il faut

Cette fonction Python réessaie ce qui mérite de l'être et s'arrête sur le reste. Deux détails comptent :

• Renvoyer une soumission après une erreur 503 ou une connexion coupée utilise la même Idempotency-Key, de sorte qu'elle ne peut jamais lancer une seconde tâche payante.
• Réessayer après l'échec d'une tâche utilise une nouvelle clé. La même clé ne ferait que renvoyer la tâche en échec.

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"])

La tâche d'exemple est un clip Seedance 2.0 Fast de 5 secondes en 480p, qui coûte $0.25 s'il réussit et rien s'il échoue. Le plafond max_cost_usd empêche un mauvais réglage de coûter plus que prévu.

Éviter les erreurs dès le départ

• Lisez les options avant d'envoyer. GET /v1/models et la page des modèles listent les tailles, les durées et les limites de références de chaque modèle. Une valeur hors de ces limites est refusée immédiatement avec 422 invalid_input.
• Téléversez les fichiers au lieu de les intégrer. POST /v1/uploads accepte des images jusqu'à 30 Mo, des clips jusqu'à 50 Mo et du son jusqu'à 15 Mo, et renvoie un lien valable 14 jours, ce qui garde le corps de la requête léger.
• Vérifiez votre solde dans le code. GET /v1/balance avant un gros lot vous évite une série d'erreurs 402. Les packs de crédits sont sur la page des tarifs.

Pour réduire le coût des tâches réussies, voir comment réduire le coût de l'API vidéo IA. La référence complète des erreurs se trouve dans la documentation ; obtenez une clé API pour essayer.