Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Asynchroner Workflow und Abfrage

Lektion 10 von 12 Aktualisiert am 2. November 2026 Mittelstufe
Auf dieser Seite
  1. Das Video-Lebenszyklus verstehen
  2. Generierungsstatus prüfen
  3. Drei Zustände, drei Aktionen
  4. Abfrage implementieren
  5. Das Abfrage-Intervall festlegen
  6. Kernaussagen

Aktualisiert am 2. November 2026. Basierend auf der xAI Video-API-Referenz: Die URL befindet sich in video.url (nicht video_url), eine Generierung verfügt über genau drei Zustände (pending, done, failed, wobei der letzte von einem Fehlercode begleitet wird), und Rate Limits werden in Anfragen pro Sekunde basierend auf dem Team-Tier ausgedrückt. Quellen: Video-Generierung · Videos-Referenz · Rate Limits.

Das Video-Lebenszyklus verstehen

Alle Video-Operationen in der xAI-API sind asynchron, und dieses Merkmal prägt Ihre Anwendungsarchitektur mehr, als Sie zunächst erwarten mögen. Ein Chat-Aufruf oder eine Bildgenerierung liefert ein Ergebnis sofort; die Video-Generierung hingegen benötigt erhebliche Verarbeitungszeit und liefert lediglich eine Bestätigung zurück. Es liegt an Ihnen, die Verfolgung zu implementieren: Abfragen Sie den Aufgabenstatus in regelmäßigen Abständen, erkennen Sie den Abschluss und laden Sie die Datei herunter. Der vollständige Zyklus besteht aus vier Schritten.

1

Anfrage einreichen

POST an den Endpunkt für Generierung, Bearbeitung oder Erweiterung. Sofortige Antwort mit einer request_id.

2

Status abfragen

GET /v1/videos/{request_id} in regelmäßigen Abständen. progress-Feld von 0 bis 100.

3

Ergebnis abrufen

Wenn der Status `done` ist (progress = 100), ist die Video-URL verfügbar.

4

Sofort herunterladen

Die Video-URL ist temporär. Laden Sie sie so schnell wie möglich herunter.

Generierungsstatus prüfen

Die Verfolgung umfasst eine einfache GET-Anfrage an den Status-Endpunkt unter Verwendung des Identifikators, der bei der Einreichung erhalten wurde.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Die Antwort stellt folgende nützliche Informationen bereit:

  • status : der aktuelle Generierungszustand
  • progress : eine ganze Zahl von 0 bis 100, die den Fortschritt angibt
  • video.url : die Video-URL, innerhalb des video-Objekts, das vorhanden ist, wenn der Status done ist, zusammen mit seiner Dauer (video.duration)
  • video.respect_moderation : ein Boolean, das angibt, ob der Inhalt den Moderationsrichtlinien entspricht
  • error : im Falle eines Fehlers ein Code (invalid_argument, permission_denied, failed_precondition, service_unavailable oder internal_error) und eine Nachricht
  • usage.cost_in_usd_ticks : die Kosten der Anfrage, in Zehntel-Milliarden Dollar

Das progress-Feld verdient eine Anmerkung: Es steuert nicht Ihre Steuerungslogik, die sich immer auf status verlassen sollte, aber es ist Gold wert für eine Benutzeroberfläche. Die Anzeige von “62%” statt eines statischen Spinners verändert die Wahrnehmung einer Wartezeit, die mehrere Minuten dauern kann, vollständig.

Drei Zustände, drei Aktionen

StatusProgressBedeutung
pending0-99Generierung läuft
done100Abgeschlossen, URL verfügbar
failedfehltGenerierung fehlgeschlagen

Solange der Status pending ist, läuft die Generierung weiter: Sie müssen lediglich in regelmäßigen Abständen abfragen und den progress an Ihre Oberfläche weiterleiten. Wenn er sich auf done ändert, ist das Video bereit, und das Einzige, was zu tun ist, ist das Lesen von video.url und das sofortige Herunterladen der Datei – diese URLs sind temporär, und die Dokumentation gibt ihre Lebensdauer nicht an, was das Speichern in einer Datenbank für einen späteren Gebrauch untersagt.

Schließlich zeigt der failed-Status einen Produktionsfehler an, und das error-Feld sagt Ihnen, welcher es ist. Die Unterscheidung ist für das Folgende wichtig: service_unavailable (Dienst vorübergehend überlastet) oder internal_error rechtfertigen einen späteren Neustart, während invalid_argument oder permission_denied – abgelehnter Prompt, ungültige Quellbild- oder Videodatei – eine Korrektur der Anfrage erfordern. Der Python-SDK signalisiert seinerseits ebenfalls über einen Fehler eine verzögerte Anfrage, die abgelaufen ist, bevor sie abgerufen wurde.

Abfrage implementieren

Die synchrone Version passt in eine einzelne Funktion. Sie läuft bis zum Timeout, bricht bei einem Fehler frühzeitig ab, indem sie den entsprechenden Code wirft, und gibt die URL zurück, sobald das Video bereit ist.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Warten auf Abschluss der Video-Generierung."""
    headers = {"Authorization": f"Bearer {api_key}"}
    debut = time.time()

    while time.time() - debut < timeout:
        resp = httpx.get(
            f"https://api.x.ai/v1/videos/{request_id}",
            headers=headers
        ).json()

        status = resp.get("status")
        progress = resp.get("progress", 0)

        if status == "done":
            return resp["video"]["url"]
        elif status == "failed":
            erreur = resp.get("error", {})
            raise RuntimeError(f"Generierung fehlgeschlagen [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"In Fortschritt... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Timeout nach {timeout} Sekunden")

In einem Dienst, der mehrere Anfragen gleichzeitig verarbeitet, wird diese blockierende Version zum Flaschenhals: Jedes Warten immobilisiert einen Thread für Minuten. Die asynchrone Umsetzung setzt den Event-Loop zwischen den Abfragen frei und ermöglicht es Ihnen, Dutzende Generierungen parallel zu verfolgen.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchrone Version der Abfrage."""
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        debut = asyncio.get_event_loop().time()

        while asyncio.get_event_loop().time() - debut < timeout:
            resp = await client.get(
                f"https://api.x.ai/v1/videos/{request_id}",
                headers=headers
            )
            data = resp.json()

            if data["status"] == "done":
                return data["video"]["url"]
            elif data["status"] == "failed":
                raise RuntimeError(f"Generierung fehlgeschlagen : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Timeout")

Das Abfrage-Intervall festlegen

Die Wahl des Intervalls balanciert Reaktionsfähigkeit gegen verschwendete Anfragen. Fünf Sekunden sind in den meisten Fällen ein guter Kompromiss. Für lange Generierungen – zehn bis fünfzehn Sekunden Video – sind zehn bis fünfzehn Sekunden zwischen Abfragen ausreichend und reduzieren den Datenverkehr. Umgekehrt rechtfertigt eine interaktive Anwendung, in der der Nutzer einen Fortschrittsbalken beobachtet, das Absenken auf zwei oder drei Sekunden. Unter einer Sekunde werden Sie jedoch nichts beschleunigen: Die Generierung verläuft in ihrem eigenen Tempo, und Sie multiplizieren lediglich Anfragen ohne Nutzen.

Kernaussagen

  • Alle Video-Operationen sind asynchron: POST zum Einreichen, GET zum Abrufen
  • Drei mögliche Zustände: pending, done, failed (mit einem Fehlercode)
  • Das progress-Feld (0-100) ermöglicht die Verfolgung des Fortschritts
  • Implementieren Sie ein Timeout und ein Abfrage-Intervall, das Ihrem Anwendungsfall entspricht
  • Video-URLs sind temporär: Laden Sie sie sofort herunter