Comment utiliser l'API de génération de vidéo à partir de texte grok-imagine-1.5-lite (curl + Python)

Si vous voulez générer une courte vidéo avec son à partir d'une simple phrase, grok-imagine-1.5-lite/text-to-video est l'option la moins chère sur hiapi capable d'atteindre la 1080P. Il prend une invite, renvoie un MP4 de 1 à 15 secondes avec l'audio déjà intégré, et s'exécute sur la même API de tâches unifiée que tous les autres modèles de la plateforme. Cette page fournit des requêtes prêtes à copier-coller, le schéma exact (vérifié contre le point de terminaison en direct, pas recopié depuis une spécification), l'aspect des vraies réponses, et les pièges que j'ai rencontrés en testant.

Tout ce qui suit a été vérifié contre l'API en direct le 2026-10-21. Les prix sont ceux que j'ai mesurés ; s'ils changent, la page de tarification fait foi.

1. Ce que vous allez construire et ce dont vous avez besoin

Objectif : envoyer une invite textuelle et récupérer un clip MP4 téléchargeable avec audio.

Vous n'avez besoin que d'une chose : une clé API hiapi. Créez-en une dans la console et conservez-la côté serveur — elle ressemble à sk-... et se place dans l'en-tête Authorization: Bearer. Il n'existe pas de chemin sans clé ; chaque requête ci-dessous doit être authentifiée.

Le modèle est asynchrone. Vous n'obtiendrez pas la vidéo directement dans la réponse du POST. Vous créez d'abord une tâche, récupérez un taskId, puis vous interrogez (ou utilisez un callback) jusqu'à ce que la tâche se termine et fournisse une URL de sortie.

2. Exemple minimal fonctionnel

Deux étapes : créer la tâche, puis interroger le résultat.

Créer la tâche (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "À l'aube, un renard roux traverse une neige fraîche, son souffle se transformant en brume blanche, lumière douce du matin, léger vent ambiant. Cinématographique, couleurs naturelles. Sans texte.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Notez la structure : model est au niveau supérieur, tout le reste est imbriqué sous input. Si vous envoyez les champs à plat (sans l'enveloppe input), l'API rejette l'ensemble du corps avec invalid input: must be a JSON object — c'est l'erreur la plus fréquente.

Une création réussie renvoie immédiatement un identifiant de tâche :

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB" }, "message": "success" }

Interroger le résultat (Python)

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("À l'aube, un renard roux traverse une neige fraîche, léger vent ambiant. Cinématographique."))

Schéma (vérifié en direct)

Les champs se placent dans input. Ce schéma est fermé — toute clé qu'il ne connaît pas renvoie une 400, donc n'envoyez pas seed, negative_prompt ou motion_mode (ils n'existent pas ici ; tous les mouvements de caméra et directions de mouvement s'expriment par la formulation de l'invite).

Champ	Type	Obligatoire	Valeurs acceptées
prompt	string	oui	texte libre
duration	integer	oui	1–15 (secondes entières ; 5.5 est rejeté)
resolution	string	—	480p, 720p, 1080p
aspect_ratio	string	—	16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16

Ce modèle n'a pas de rapport d'aspect auto (son équivalent image-vers-vidéo en a un ; ce point de terminaison texte-vers-vidéo n'en a pas). Spécifiez explicitement le ratio, sinon vous obtiendrez le ratio par défaut du modèle.

Voici une vraie réponse d'une tâche terminée :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

Voici un clip généré par ce modèle (sortie de référence fournie par hiapi pour grok-imagine-1.5-lite/text-to-video, générée à partir de l'invite de son exemple de documentation — "Au lever du soleil, une montgolfière en verre flotte au-dessus de rizières en terrasses") :

3. Passer en production

Utilisez un callback plutôt que le polling. Le polling convient aux scripts ; pour un serveur, ajoutez callback afin de ne pas garder la requête ouverte. Lorsque la tâche atteint un état terminal, la plateforme envoie les détails de la tâche en POST à votre URL :

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

Pour ce type de tâche, when n'accepte que "final". Dédupliquez par taskId dans votre handler — les callbacks peuvent être réessayés, donc traitez le handler comme idempotent.

Les URL de sortie expirent. Remarquez storage: "temp" et l'horodatage unix expireAt — les sorties temporaires sont stockées sur temp.hiapi.ai pendant environ 7 jours, après quoi elles renvoient une 404. Ne conservez pas de liens chauds. Téléchargez les octets dès que la tâche réussit, ou appelez le point de terminaison de promotion du stockage pour déplacer l'artefact vers un stockage permanent avant l'expiration du TTL.

La facturation se fait à la seconde de sortie. Le coût est déterminé uniquement par duration et la résolution demandée. Lors de mes tests : 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. Ainsi, un clip de 5 secondes en 720P coûte environ $0.215, un clip de 5 secondes en 1080P environ $1.00, et un clip de 1 seconde en 480P environ $0.029. Le tarif 1080P est environ 5 fois celui du 720P — ne l'utilisez que si vous avez vraiment besoin de cette résolution. Voir les chiffres à jour sur la page de tarification.

Gestion des erreurs. Les requêtes rejetées renvoient une HTTP 400 avec un message précis que vous pouvez journaliser et traiter. La validation a lieu avant la création de toute tâche, donc une 400 ici n'entraîne aucun frais. Voici de vraies réponses que j'ai déclenchées :

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

Une tâche acceptée mais qui échoue ensuite apparaît sous la forme data.status: "fail" avec un objet data.error sur le point de terminaison de détail — pas comme une erreur HTTP — donc vérifiez status, ne vous fiez pas au code HTTP du polling.

4. Ce que j'ai réellement observé

J'ai lancé une vraie génération pour confirmer le flux de bout en bout (pas seulement le schéma) : duration: 1, resolution: "480p", aspect_ratio: "16:9".

• Cela fonctionne réellement et facture — le POST a renvoyé un taskId, et la tâche s'est terminée avec une vraie URL de sortie. Le rendu côté serveur d'un clip de 1 seconde a pris environ 51 secondes ; même un petit clip n'est pas instantané, donc fixez un délai de polling généreux (j'ai mis 300 secondes).
• Les tâches passent par des états intermédiaires. Le champ status passe par handling → archiving → success. Seuls success et fail sont terminaux ; ne traitez pas archiving comme terminé.
• La 480P en 16:9 se rend en 848×480 H.264. En lançant ffprobe sur le fichier téléchargé : un flux vidéo H.264 (848×480), plus un flux de miniature MJPEG intégré. Ce fichier de 495 Ko est un MP4 valide.
• L'audio est toujours intégré. Même si mon invite ne mentionnait que « léger vent ambiant », la sortie contient une piste AAC — le modèle synthétise un audio correspondant et le mélange dans le même MP4. Il n'y a pas d'URL audio séparée ni d'option pour le désactiver ; si vous avez besoin d'un clip muet, retirez la piste vous-même (ffmpeg -an).

Note de périmètre : j'ai validé le contrat d'API, les trois types d'erreurs ci-dessus, et un rendu 480P. Je n'ai pas évalué la qualité des sorties 720P/1080P ni des durées longues (15 secondes), donc je ne fais pas d'affirmations de qualité à ce sujet — je dis seulement que le schéma les accepte et facture à la seconde.

5. Comparaison entre l'API vidéo Lite et standard Grok Imagine

Choisissez le bon point de terminaison avant de construire :

• grok-imagine-1.5-lite/text-to-video (cette page) : 480P/720P/1080P, 1–15 secondes (donc des clips de 1 ou 2 secondes sont possibles), prix $0.029–$0.20/s. C'est le seul point de terminaison texte-vers-vidéo de génération 1.5 hébergé par hiapi, et le seul palier Grok t2v capable d'atteindre la 1080P.
• grok-imagine/text-to-video (ancien palier standard, voir ce guide) : moins cher à la seconde ($0.0114–$0.0214/s) et propose des Motion Modes, mais plafonne à 720p et exige une durée de 6–30 secondes — impossible de générer un clip de moins de 6 secondes.

Donc « lite » ici n'est pas l'option la moins chère à la seconde ; c'est le palier qui débloque la 1080P et les clips très courts. Si vous voulez fournir une image statique au lieu de texte, utilisez le point de terminaison grok-imagine-1.5-lite/image-to-video du même palier (tarification identique, entrée image_urls).

6. Liens associés

• Page du modèle grok-imagine-1.5-lite texte-vers-vidéo / aire de test
• Créer une tâche — référence API
• Obtenir les détails d'une tâche — référence API
• Tarification

FAQ

Dois-je interroger, ou y a-t-il un callback ? Les deux fonctionnent. Les scripts utilisent le polling avec GET /v1/tasks/{taskId} ; les serveurs joignent callback.url et définissent when à "final". Dédupliquez par taskId.

Pourquoi ma requête renvoie 400 avec « must be a JSON object » ? Vos champs ne sont pas enveloppés dans input. Le corps de la requête doit être {"model": "...", "input": { ... }}.

Peut-on désactiver l'audio ? Pas lors de la requête — chaque sortie inclut une piste AAC mixée. Si vous avez besoin de silence, retirez-la en aval avec ffmpeg -an.

Combien de temps une URL de sortie est-elle valide ? C'est une URL temporaire avec expireAt (environ 7 jours). Téléchargez immédiatement ou promouvez vers un stockage permanent ; ne créez pas de lien chaud.

Quelle est la requête valide la moins chère ? 1 seconde en 480P coûte environ $0.029. C'est un bon moyen de faire une requête canari avant un traitement par lots pour confirmer que votre clé a du solde.