Fehlercodes der KI-Video-API: Was sie bedeuten und wann Sie es erneut versuchen sollten

Zwei Stellen, an denen ein Fehler auftreten kann

Ein Video- oder Bild-Job kann an zwei Punkten scheitern, und Ihr Code muss beide behandeln:

1. Beim Absenden. POST /v1/generations antwortet mit einem HTTP-Fehlerstatus und einem Body wie {"error": {"code": "...", "message": "..."}}. Es wurde nichts gestartet und nichts berechnet.
2. Während der Ausführung. Das Absenden war mit 202 erfolgreich, aber der Job endet später mit status: "failed". Er enthält error mit einem code, einem message, den Sie der anfragenden Person anzeigen können, und retryable.

Ein fehlgeschlagener Job wird bei keinem Modell berechnet. Der Preis wird beim Absenden von Ihrem Guthaben reserviert und freigegeben, wenn der Job fehlschlägt.

HTTP-Fehler beim Absenden

Faustregel: 429, 500 und 503 lohnen sich mit Backoff erneut zu versuchen; alles im Bereich 4xx außer 429 bedeutet, dass die Anfrage selbst geändert werden muss.

Warum ein Job nach dem Start fehlschlägt

Im Hintergrund wechselt ein Job, der auf eine ausgelastete oder defekte Route trifft, selbstständig zur nächsten Route. Wenn Sie also model_busy oder all_routes_failed sehen, wurden bereits alle Routen versucht. Das Feld attempts gibt an, wie viele. Meist genügt es, ein bis zwei Minuten zu warten und es dann erneut zu versuchen.

Ablehnungen wegen Inhalten

content_policy ist der Fehler, auf den man am häufigsten stößt. Die Entscheidung trifft das Modell, nicht die API, und reason nennt die ausgelöste Regel. Häufige Ursachen sind der Name oder das Gesicht einer bekannten Person im Prompt oder in einem Referenzbild (real_person), Marken und bekannte Figuren (copyright) sowie alles, was nach einer minderjährigen Person aussieht. Dieselbe Anfrage erneut zu senden hilft nicht; formulieren Sie den Prompt um oder ändern Sie das Bild. Modelle sind unterschiedlich streng, derselbe Prompt kann bei einem durchgehen und bei einem anderen abgelehnt werden.

Eine Retry-Schleife, die das Richtige tut

Dieser Python-Helfer wiederholt, was sich lohnt, und bricht bei allem anderen ab. Zwei Details sind wichtig:

• Wird ein Absenden nach einem 503 oder einer abgebrochenen Verbindung erneut gesendet, verwendet es denselben Idempotency-Key, sodass nie ein zweiter, kostenpflichtiger Job gestartet werden kann.
• Ein neuer Versuch, nachdem ein Job fehlgeschlagen ist, verwendet einen neuen Schlüssel. Derselbe Schlüssel würde nur den fehlgeschlagenen Job zurückgeben.

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

Der Beispiel-Job ist ein 5 Sekunden langer 480p-Clip mit Seedance 2.0 Fast, der $0.25 kostet, wenn er gelingt, und nichts, wenn er fehlschlägt. Die Obergrenze max_cost_usd verhindert, dass eine falsche Einstellung mehr kostet als erwartet.

Fehler von vornherein vermeiden

• Lesen Sie die Optionen, bevor Sie senden. GET /v1/models und die Modellseite listen für jedes Modell Größen, Längen und Referenzlimits auf. Ein Wert außerhalb davon wird sofort mit 422 invalid_input abgelehnt.
• Laden Sie Dateien hoch, statt sie einzubetten. POST /v1/uploads nimmt Bilder bis 30 MB, Clips bis 50 MB und Audio bis 15 MB an und liefert einen Link, der 14 Tage gültig ist. So bleibt der Request-Body klein.
• Prüfen Sie Ihr Guthaben im Code. GET /v1/balance vor einem großen Batch erspart eine Serie von 402-Fehlern. Credit-Pakete finden Sie auf der Preisseite.

Wie Sie die Kosten erfolgreicher Jobs senken, lesen Sie unter KI-Video-API-Kosten senken. Die vollständige Fehlerreferenz steht in der Dokumentation; holen Sie sich einen API-Schlüssel, um es auszuprobieren.