Tutoriel pour débutants sur l'API vidéo Grok Imagine

L'API vidéo Grok permet aux développeurs de générer des vidéos à partir d'invites textuelles, et pour les workflows pris en charge, d'utiliser également une image de départ ou d'autres références. Contrairement aux réponses textuelles synchrones, la génération vidéo est asynchrone : la première requête renvoie un identifiant de tâche, et votre application doit interroger jusqu'à ce que le résultat soit prêt.

Ce tutoriel explique l'architecture et fournit un exemple minimaliste en Python. Si vous souhaitez évaluer la qualité visuelle avant d'écrire du code, vous pouvez tester les invites dans l'espace de travail Grok Imagine d'Elser AI, puis migrer les spécifications de prise de vue réussies vers l'API.

De quoi avez-vous besoin

• Un compte développeur xAI ;
• une clé API stockée en toute sécurité ;
• Python 3.10 ou version ultérieure ;
• paquet requests ;
• Stockage persistant des fichiers vidéo terminé ;
• Stratégie de budget et de nouvelle tentative.

Ne jamais coder en dur les clés API dans le code source ni les exposer dans du JavaScript côté navigateur.

Comment fonctionne le flux de travail API

1. Envoyez une requête de génération à /v1/videos/generations.
2. Recevez un request_id.
3. Interroger /v1/videos/{request_id}.
4. Arrêter lorsque l'état devient done ou qu'une panne terminale se produit.
5. Veuillez télécharger la vidéo retournée à temps, car l'URL générée est temporaire.
6. Enregistrer les métadonnées, les invites, le modèle, les paramètres et les coûts pour l'audit et la reproductibilité.

Exemple minimal de texte en vidéo

import os
import time
from pathlib import Path

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" : (
        Une boîte de produit noire mate s'ouvre sur une surface réfléchissante.
        Un éclairage corail doux illumine le produit pendant le fonctionnement de l'appareil photo.
        "Plan lent avant. Éclairage de studio haut de gamme, dynamique réel, sans texte."
    ),
    "duration": 6,
    "resolution": "720p",
}

create = requests.post(
    f"{BASE_URL}/videos/generations"
    headers=EN-TÊTES,
    json=charge,
    timeout=60,
)
create.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()

    Si le résultat["Statut"] "Terminé"
        video_url = résultat["Vidéo"]["url"]
        video_response = requests.get(video_url, timeout=180)
        video_response.raise_for_status()
        Path("output.mp4").write_bytes(video_response.content)
        print("已保存 output.mp4")
        Interruption

    Si le résultat["Statut"] Dans {"expired", "failed", "cancelled"} :
        raise RuntimeError(f"Génération terminée, état : {result['status']}")

    time.sleep(5)
else :
    Erreur de délai d'attente déclenchée ("La génération vidéo n'a pas été terminée avant l'échéance")

Avant le déploiement, veuillez vérifier l'architecture actuelle de l'API xAI. Les noms des modèles, les paramètres pris en charge et l'état des réponses peuvent changer.

Conversion d'image en vidéo

La documentation de xAI prend en charge l'utilisation d'URL d'images publiques ou d'URI de données base64 pour la génération axée sur les images. Conceptuellement, la requête ajoute un objet image :

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Conserver le sujet, les vêtements et l'arrière-plan."
        "Le personnage principal se tourne vers la fenêtre, tandis que la caméra avance lentement."
    ),
    "image" {"url": "https://example.com/source-image.png"},
    "duration": 6,
    "resolution": "720p",
}

Si l'entrée est privée, veuillez utiliser des URL signées à courte durée de validité. N'exposez pas les contenus médiatiques des clients en public simplement pour satisfaire aux exigences de l'API.

Gestion des erreurs en environnement de production

Les clients en environnement de production doivent gérer :

• Échec de l'authentification ;
• Erreur de validation ;
• Refusé après vérification ;
• Limitation de débit ;
• Délai d'attente réseau dépassé ;
• Liens vers des postes expirés ou des résultats ;
• Soumission en double ;
• Panne de stockage partielle ;
• Le budget du compte est épuisé.

Pour les erreurs pouvant être retentées, utilisez une stratégie de backoff exponentiel avec gigue. Ne retentez pas indéfiniment les échecs de validation ou de vérification. Ajoutez une clé d'idempotence ou maintenez votre propre journal des tâches pour éviter que les tentatives réseau n'entraînent des doublons vidéo inattendus.

Contrôle des coûts

xAI fixe le prix des vidéos en fonction du nombre de secondes générées, le tarif variant selon le modèle et la résolution. Les entrées média peuvent également entraîner des frais. Le stockage conserve les données d'utilisation renvoyées pour chaque tâche, incluant le modèle, la résolution et la durée.

Les mesures de sécurité utiles incluent :

• Durée maximale de chaque requête ;
• Limite de dépenses quotidiennes par utilisateur ;
• Mode brouillon basse résolution ;
• Une approbation est requise avant le re-rendu en haute résolution ;
• Limite du nombre de tentatives automatiques ;
• Alerte de génération anormale ;
• Rapport de coûts pour chaque segment approuvé.

Conception des files d'attente et de la concurrence

Les tâches vidéo doivent être mises en file d’attente. Les nœuds de travail soumettent des requêtes, interrogent de manière responsable et transfèrent les fichiers terminés vers un stockage d’objets persistant. La base de données de votre application doit suivre :

• ID de poste interne ;
• ID de requête xAI ;
• Utilisateurs et projets ;
• Références aux invites et aux entrées ;
• Statut et progression ;
• horodatage ;
• Modèle et paramètres ;
• URL de stockage de sortie ;
• Coût et résultat de l'audit.

Respectez les limites de débit du niveau de compte actuel. Si un trop grand nombre d'opérations parallèles entraîne un contrôle de débit ou une perte de contrôle des coûts, cela n'apporte aucun avantage.

Sécurité et confidentialité

Vérifier les droits de l'utilisateur sur les images téléchargées ainsi que les autorisations des personnes identifiables. Empêcher le système de créer des images intimes non consenties, des usurpations frauduleuses, des contenus abusifs ou illégaux. Conserver uniquement les médias et journaux nécessaires au service, et publier une politique de suppression claire.

Il est interdit de retirer le filigrane ou l'identification de la source du fournisseur. Pour les contenus très diffusés, politiques, médicaux, financiers ou sensibles à l'identité, une vérification humaine est requise.

Évaluation sans code avant l'intégration de l'API

Lorsque les spécifications créatives sont validées, la mise en œuvre des projets API devient plus facile. Utilisez Grok Imagine Video sur Elser AI pour tester les prompts, l'adéquation des images de référence, le rapport hauteur/largeur et les critères d'acceptation des plans. Une fois que l'équipe peut décrire de manière fiable des plans utilisables, les parties répétitives peuvent être automatisées.

Liste de vérification de démarrage

• La clé API est stockée dans le gestionnaire de clés.
• Le modèle actuel et ses paramètres ont été vérifiés conformément à la documentation xAI.
• Logique de file d'attente, de délai d'attente, de nouvelle tentative et d'idempotence testée.
• Sortie transférée depuis une URL temporaire.
• Limites de consommation par utilisateur et globales activées.
• Traitement des échecs de vérification, sans réessai aveugle.
• Droits de source et consentement confirmés.
• Exclure les médias sensibles et les identifiants des journaux.
• Les règles relatives aux filigranes et à la divulgation de l'IA sont documentées.