Comment utiliser l'API Grok Imagine pour la génération de vidéos à partir de texte : curl, Python et une requête exécutable

Grok Imagine est le modèle de génération vidéo de xAI, et HiAPI expose sa variante texte-vers-vidéo via le même point de terminaison asynchrone unifié que tous les autres modèles de génération : POST /v1/tasks. Vous envoyez un prompt (avec éventuellement une durée, un mode, un rapport d'aspect et une résolution), obtenez immédiatement un taskId, puis récupérez une URL .mp4 une fois la tâche terminée.

Ce guide est le chemin le plus court vers une requête exécutable : le schéma d'entrée exact (vérifié contre l'API en ligne, y compris l'erreur 400 que vous rencontrerez si vous vous trompez de nom de champ), un flux curl copiable-collable, un petit client Python avec polling, et le modèle de callback que vous utiliserez en production.

Ce que vous allez construire, et ce qu'il vous faut

Objectif : transformer un prompt textuel en un clip vidéo de 6 à 30 secondes, entièrement via HTTP, grâce à grok-imagine/text-to-video.

Une seule chose vous est nécessaire : une clé API HiAPI. Créez-en une dans le tableau de bord HiAPI — une clé unique fonctionne pour tous les modèles, donc si vous appelez déjà des modèles d'image sur HiAPI, la même clé fonctionne ici. Les requêtes s'authentifient avec l'en-tête bearer standard :

Authorization: Bearer sk-<your-key>

Schéma d'entrée (avant d'écrire la moindre ligne de code)

L'API de tâches valide strictement le input selon le modèle — les champs inconnus sont rejetés avec un 400 plutôt que silencieusement ignorés. Voici le schéma complet de grok-imagine/text-to-video :

Champ	Type	Obligatoire	Valeurs	Valeur par défaut
prompt	string	oui	jusqu'à 5000 caractères, l'anglais donne les meilleurs résultats	—
duration	integer	non	6–30 (secondes)	6
mode	enum	non	fun, normal	normal
aspect_ratio	enum	non	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	non	480p, 720p	480p

Trois points méritent d'être connus à l'avance :

• mode est le commutateur de « mode de mouvement ». normal est équilibré ; fun produit un mouvement plus créatif et plus exagéré. Si vous avez vu ailleurs les modes de Grok Imagine décrits sous d'autres noms, le paramètre API est bien mode — envoyer quelque chose comme motion_mode vous vaudra 400 additional properties 'motion_mode' not allowed.
• duration influe linéairement sur le coût. Grok Imagine facture à la seconde produite, donc un clip de 30 secondes coûte 5 fois le prix d'un clip de 6 secondes. Le tarif actuel par seconde figure sur la page de tarification HiAPI.
• Le rapport d'aspect par défaut est 2:3 (portrait). Si vous voulez du grand écran, passez explicitement 16:9 — ce détail surprend les utilisateurs qui migrent depuis des modèles par défaut en paysage.

Les valeurs hors limites échouent rapidement avec un message descriptif, par exemple duration: 31 renvoie :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Exemple minimal exécutable : curl

Deux appels : créer la tâche, puis la sonder.

1. Créer la tâche :

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Notez que l'id du modèle est la chaîne brute grok-imagine/text-to-video — pas de préfixe de fournisseur, pas de suffixe de version.

2. Sonder jusqu'à l'état terminal :

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

L'URL .mp4 est temporaire — expireAt est un horodatage Unix à environ une semaine. Téléchargez les octets dès que la tâche réussit et persistez-les vous-même ; ne faites pas de hotlink vers les URL temp.hiapi.ai depuis un endroit exposé aux utilisateurs. (Si vous avez déjà rencontré des liens de sortie invalides, c'est la raison — voir URL de sortie hiapi expirée : téléchargez avant expiration.)

Python : un petit client avec polling

Le même flux sous forme de script réutilisable — création, polling avec échéance, téléchargement :

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

Un clip de 6 secondes se termine généralement bien avant le délai limite de 15 minutes ci-dessus ; les durées plus longues prennent proportionnellement plus de temps, donc conservez ce délai généreux pour les tâches de 30 secondes.

Considérations pour la production

Privilégiez les callbacks au polling. Pour tout ce qui dépasse un script, passez un objet callback de premier niveau lors de la création, et HiAPI enverra en POST l'état terminal de la tâche à votre point de terminaison — plus besoin de boucle de polling à surveiller :

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when n'accepte que "final" (vous recevez un seul POST lorsque la tâche atteint success ou fail, pas de progression incrémentale). Règle empirique : le polling convient aux CLI, aux travaux par lots et à tout scénario de courte durée ; les callbacks conviennent aux backends web, sans quoi vous immobilisez la capacité de vos workers pendant des rendus de plusieurs minutes. Si votre point de terminaison de callback semble ne rien recevoir, consultez pourquoi votre callback de tâche hiapi ne se déclenche pas.

Idempotence. La création de tâche n'est pas idempotente — réessayer une requête de création qui a expiré peut produire deux tâches facturées. Enregistrez le taskId dès que vous l'obtenez, et en cas d'échec ambigu (timeout réseau à la création), vérifiez votre historique de tâches avant de resoumettre. Comme duration est facturé à la seconde, une tâche de 30 secondes dupliquée est le genre de duplication coûteuse.

Gestion des erreurs. Les deux catégories d'erreurs que vous verrez réellement :

• Erreurs de schéma 400 (error_code: "INVALID_REQUEST") — nom de champ incorrect, durée hors limites, valeur d'énumération invalide. Elles sont déterministes ; corrigez la requête, ne réessayez pas.
• Échecs d'authentification — une clé invalide ou une clé sans accès à ce modèle renvoie 401, avec "code": "permission_denied" et le message "This API key cannot use the selected model." Vérifiez la clé dans le tableau de bord et assurez-vous que le modèle est activé pour elle.
• Échecs au niveau de la tâche — la création réussit, mais la tâche atteint ensuite l'état terminal avec status: "fail" et un objet error (politique de contenu, capacité en amont). Ceux-là méritent une nouvelle tentative avec backoff. Si une tâche semble bloquée en handling, voir diagnostiquer les tâches /v1/tasks bloquées ou expirées.

Pour aller plus loin

• Page du modèle Grok Imagine texte-vers-vidéo — aire de jeux et tarification actuelle
• Référence d'entrée du modèle — le schéma canonique de ce modèle
• Créer une tâche et Obtenir les détails d'une tâche — l'enveloppe complète de l'API asynchrone
• Démarrage rapide — réaliser votre premier appel HiAPI de bout en bout, et Authentification pour la gestion des clés

Questions fréquentes

Qu'est-ce que l'API Grok Imagine et comment y accéder ? Grok Imagine est le modèle de génération vidéo de xAI. Via HiAPI, vous l'appelez sous le nom grok-imagine/text-to-video sur le point de terminaison unifié POST /v1/tasks avec une seule clé HiAPI — aucun compte xAI ni SDK séparé n'est nécessaire.

Quelle peut être la durée d'une vidéo Grok Imagine ? duration accepte un entier de 6 à 30 secondes (par défaut 6). Les valeurs hors de cette plage sont rejetées à la création avec un 400, et la facturation se fait à la seconde produite.

Quelle est la différence entre les modes fun et normal ? normal (par défaut) offre un mouvement équilibré et réaliste ; fun penche vers plus de créativité et d'exagération. C'est le seul commutateur de style de mouvement exposé par l'API — il se choisit par requête, pas par compte.

grok-imagine/text-to-video prend-il en charge la 1080p ? Pas pour le moment — resolution accepte 480p (par défaut) ou 720p. Si vous avez besoin d'une résolution de sortie plus élevée, agrandissez en aval ou comparez avec d'autres modèles vidéo sur la page des modèles.

Puis-je utiliser Grok Imagine pour animer une image existante ? Pas avec ce modèle — il ne prend en charge que le texte. Un modèle distinct, grok-imagine/image-to-video, existe sur le même point de terminaison de tâches et accepte une entrée image ; le cycle de vie asynchrone (création → polling/callback → téléchargement) est identique.

L'API Grok Imagine a-t-elle un niveau gratuit ? La génération est facturée à la seconde de vidéo depuis votre solde HiAPI — il n'existe pas de point de terminaison gratuit sans clé. Les tarifs actuels figurent sur la page de tarification ; pour savoir à quoi ressemble concrètement le « gratuit » dans ce domaine, cette comparaison des API gratuites de texte-vers-vidéo couvre les différentes options.