Grok Imagine Video API Tutorial für Anfänger

Die Grok-Video-API ermöglicht Entwicklern, aus einer Textaufforderung und, bei unterstützten Workflows, einem Startbild oder anderen Referenzen Videos zu generieren. Im Gegensatz zu einer synchronen Textantwort ist die Videogenerierung asynchron: Die erste Anfrage gibt eine Job-ID zurück, und Ihre Anwendung fragt ab, bis das Ergebnis bereit ist.

Dieses Tutorial erklärt die Architektur und liefert ein minimales Python-Beispiel. Wenn Sie die visuelle Qualität vor der Code-Erstellung bewerten möchten, testen Sie Prompts im Elser AI’s Grok Imagine workspace und übertragen Sie dann die erfolgreiche Aufnahme-Spezifikation in die API.

Was du brauchst

• ein xAI-Entwicklerkonto;
• ein sicher gespeicherter API-Schlüssel;
• Python 3.10 oder neuer;
• das requests-Paket;
• dauerhafte Speicherung für abgeschlossene Videodateien;
• eine Budget- und Wiederholungsrichtlinie.

Hard-codieren Sie niemals einen API-Schlüssel in der Quellcodeverwaltung und setzen Sie ihn nicht in browser-seitigem JavaScript ein.

Wie der API-Workflow funktioniert

1. Senden Sie eine Generierungsanfrage an /v1/videos/generations.
2. Empfangen Sie eine request_id.
3. /v1/videos/{request_id} abfragen.
4. Stoppen, wenn der Status done ist oder ein endgültiger Fehler auftritt.
5. Laden Sie das zurückgegebene Video umgehend herunter, da generierte URLs nur vorübergehend gültig sind.
6. Metadaten, Prompt, Modell, Einstellungen und Kosten für Prüfung und Reproduzierbarkeit speichern.

Minimales Text-zu-Video-Beispiel

import os
import time
von pathlib import Pfad

import requests


API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Ein mattschwarzes Produktgehäuse öffnet sich auf einer reflektierenden Oberfläche."
        "Ein sanftes Korallenlicht enthüllt das Produkt, während die Kamera ihre Arbeit verrichtet"
        "Ein langsames Heranzoomen. Hochwertige Studio-Beleuchtung, realistische Bewegung, kein Text."
    ),
    "duration": 6,
    "resolution": "720p",
}

create = requests.post(
    f"{BASE_URL}/videos/generations"
    headers=HEADERS,
    json=payload,
    timeout=60,
)
erstellen.raise_for_status()
request_id = create.json()["request_id"]

deadline = time.time() + 15 * 60
while time.time() < deadline:
    status_response = requests.get(
        f"{BASE_URL}/videos/{request_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    )
    status_response.raise_for_status()
    result = status_response.json()

    wenn Ergebnis["Status"] == "erledigt":
        video_url = Ergebnis["Video"]["url"]
        video_response = requests.get(video_url, timeout=180)
        video_response.raise_for_status()
        Path("output.mp4").write_bytes(video_response.content)
        print("Gespeichert output.mp4")
        Pause

    wenn Ergebnis["Status"] in {"abgelaufen", "fehlgeschlagen", "abgebrochen"}:
        raise RuntimeError(f"Generierung endete mit Status: {result['status']}")

    time.sleep(5)
else:
    raise TimeoutError("Die Videogenerierung wurde nicht vor der Frist abgeschlossen")

Überprüfe vor der Bereitstellung das aktuelle xAI-API-Schema. Modellnamen, unterstützte Parameter und Antwortstatus können sich ändern.

Bild-zu-Video

Die Dokumentation von xAI unterstützt eine öffentliche Bild-URL oder einen Base64-Daten-URI für die bildgesteuerte Generierung. Konzeptionell fügt die Anfrage ein Bildobjekt hinzu:

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Bewahren Sie das Motiv, die Kleidung und den Hintergrund."
        "Das Subjekt wendet sich dem Fenster zu, während die Kamera langsam einfährt."
    ),
    "Bild": {"url": "https://example.com/source-image.png"},
    "duration": 6,
    "resolution": "720p",
}

Verwenden Sie kurzlebige signierte URLs, wenn die Eingabe privat ist. Setzen Sie Kundenmedien nicht öffentlich aus, nur um eine API-Anforderung zu erfüllen.

Fehlerbehandlung in der Produktion

Ein Produktionsclient sollte Folgendes handhaben:

• Authentifizierungsfehler;
• Validierungsfehler;
• Ablehnung der Moderation;
• Ratenbegrenzung;
• Netzwerk-Zeitüberschreitungen;
• abgelaufene Jobs oder Ergebnis-URLs;
• doppelte Einreichungen;
• teilweiser Speicherausfall;
• Konto-Budgeterschöpfung.

Verwenden Sie exponentielles Backoff mit Jitter für wiederholbare Fehler. Wiederholen Sie Validierungs- oder Moderationsfehler nicht unbegrenzt. Fügen Sie einen Idempotenzschlüssel hinzu oder führen Sie einen eigenen Auftragsdatensatz, damit eine Netzwerkwiederholung kein unerwartetes doppeltes Video erzeugt.

Kostenkontrollen

xAI berechnet Videos pro generierter Sekunde, wobei die Preise je nach Modell und Auflösung variieren. Auch Medieneingaben können Kosten verursachen. Speichern Sie für jeden Auftrag das Modell, die Auflösung, die Dauer und die zurückgegebenen Nutzungsdaten.

Nützliche Schutzmaßnahmen umfassen:

• maximale Dauer pro Anfrage;
• tägliche Ausgabenobergrenzen pro Benutzer;
• Entwurfsmodus mit niedrigerer Auflösung;
• Genehmigung vor hochauflösenden Nachrendern;
• eine Begrenzung automatischer Wiederholungsversuche;
• Benachrichtigungen bei ungewöhnlichem Generierungsvolumen;
• Kostenbericht pro genehmigtem Clip.

Warteschlangen- und Parallelitätsdesign

Video-Jobs sollten in eine Warteschlange eingereiht werden. Arbeiter senden Anfragen ein, fragen verantwortungsvoll ab und übertragen abgeschlossene Dateien in einen dauerhaften Objektspeicher. Ihre Anwendungsdatenbank sollte Folgendes nachverfolgen:

• interne Job-ID;
• xAI-Anfrage-ID;
• Benutzer und Projekt;
• Eingabeaufforderungen und Eingabereferenzen;
• Status und Fortschritt;
• Zeitstempel;
• Modell und Einstellungen;
• Speicher-URL für die Ausgabe;
• Kosten und Moderationsergebnis.

Respektieren Sie die Ratenlimits der aktuellen Kontostufe. Mehr Parallelität ist nicht sinnvoll, wenn sie Drosselung oder unkontrollierte Kosten verursacht.

Sicherheit und Datenschutz

Validieren Sie, dass Nutzer Rechte an hochgeladenen Bildern haben und die Erlaubnis erkennbarer Personen vorliegt. Sorgen Sie dafür, dass das System offensichtliche Versuche zur Erstellung nicht einvernehmlicher intimer Bildaufnahmen, täuschender Identitätsnachahmung, Ausbeutung oder illegaler Inhalte ablehnt. Behalten Sie nur die Medien und Protokolle, die für den Dienst erforderlich sind, und veröffentlichen Sie eine klare Löschrichtlinie.

Entfernen Sie keine Wasserzeichen oder Herkunftskennzeichnungen von Anbietern. Führen Sie eine menschliche Überprüfung für Inhalte mit hoher Reichweite, politische, medizinische, finanzielle oder identitätssensible Inhalte durch.

No-Code-Bewertung vor der API-Integration

Ein API-Projekt ist einfacher, wenn die kreative Spezifikation bereits erprobt ist. Nutzen Sie Grok Imagine Video auf Elser AI, um Prompts, die Eignung von Referenzbildern, Seitenverhältnisse und Akzeptanzkriterien für Aufnahmen zu testen. Sobald das Team zuverlässig eine brauchbare Aufnahme beschreiben kann, automatisieren Sie den wiederholbaren Teil.

Startliste

• API-Schlüssel in einem Secrets-Manager gespeichert.
• Aktuelles Modell und Parameter wurden mit der xAI-Dokumentation abgeglichen.
• Warteschlangen-, Timeout-, Wiederholungs- und Idempotenzlogik getestet.
• Ausgaben, die von temporären URLs übertragen wurden.
• Pro-Benutzer- und globale Ausgabenlimits aktiviert.
• Moderationsfehler werden ohne blinde Wiederholungsversuche behandelt.
• Quellenrechte und Einwilligung bestätigt.
• Logs schließen sensible Medien und Anmeldeinformationen aus.
• Wasserzeichen- und KI-Offenlegungsregeln dokumentiert.