Générer des vidéos courtes à partir d'images produits statiques : grok-imagine/image-to-video sur l'API hiapi

Le contenu vidéo court pour les produits souffre d'un problème d'approvisionnement. Une courte vidéo prête à diffuser impliquait autrefois un tournage : du temps en studio, du motion design, un monteur. Mais si vous exploitez déjà un catalogue e-commerce, vous disposez de la matière première : des milliers d'images produits statiques.grok-imagine/image-to-video (le point de terminaison xAI Grok Imagine image-vers-vidéo) transforme ces images statiques en courts métrages cinématographiques de 6 à 30 secondes en un seul appel API asynchrone, et son conditionnement par image de référence permet à votre produit de continuer à ressembler à votre produit.

Ce guide est un flux de travail de bout en bout sur l'API hiapi : animer une seule image de catalogue, verrouiller la cohérence du sujet avec plusieurs images de référence, choisir les paliers de durée et de résolution pour l'économie du fil d'actualité, et traiter l'ensemble du catalogue en une file de vidéos courtes verticales. Chaque court métrage intégré ci-dessous est une véritable première sortie, non montée, provenant de l'API en production — générée pour cet article à partir d'images statiques de notre bibliothèque de médias, avec la consigne et les réglages exacts fournis à côté.

Modèle, limites et tarifs

grok-imagine/image-to-video fonctionne sur l'interface de tâches asynchrones de hiapi (POST /v1/tasks). Voici le schéma d'entrée que nous avons testé et vérifié pour cet article :

• image_urls (tableau, obligatoire) — une ou plusieurs URL d'images de référence accessibles publiquement. Les URL privées ou non récupérables échouent à l'étape de normalisation, et non par une erreur de schéma ; hébergez donc d'abord vos images de référence à un emplacement public.
• prompt (chaîne, facultatif) — indications de mouvement, de caméra et d'ambiance. Sans consigne, le modèle improvise ; pour du contenu produit, vous devriez toujours en fournir une.
• duration (entier, 6–30 secondes)
• resolution (480p ou 720p)
• aspect_ratio (1:1, 2:3, 3:2, 16:9, 9:16)

Il n'existe aucun champ motion_mode, seed ou consigne négative — les champs inconnus sont rejetés avec une erreur 400. Tout le contrôle du mouvement repose sur la formulation de la consigne.

Un comportement que nous avons rencontré en générant les courts métrages de cet article : lorsque aspect_ratio ne correspond pas au rapport d'aspect de l'image de référence elle-même, c'est généralement l'image de référence qui l'emporte. Nous avons demandé 9:16 pour les trois exécutions ci-dessous ; deux images statiques sources carrées ont donné des courts métrages carrés (960×960 et 544×544), tandis que l'exécution dont la première image de référence était en paysage a livré une véritable vidéo verticale de 720×1280. Si votre fil d'actualité exige du 9:16 garanti, recadrez l'image statique de référence en 9:16 avant de soumettre, plutôt que de dépendre de ce paramètre.

Le prix est facturé à la seconde de sortie, d'après la page tarifaire hiapi au moment de la rédaction :

Palier	Prix par seconde	Court métrage de 6 s	Court métrage de 15 s	Court métrage de 30 s
480p	$0.0114	$0.068	$0.171	$0.342
720p	$0.0214	$0.128	$0.321	$0.642

Ce prix façonne tout le flux de travail : un court métrage principal de 6 secondes en 720p coûte environ 13 cents, tandis qu'un brouillon en 480p coûte environ la moitié. Vous pouvez tout à fait vous permettre d'itérer.

Soumettre → interroger → télécharger

Le cycle de vie d'une tâche se déroule en trois temps : soumettre, interroger, télécharger. Soumission avec curl :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-video",
    "input": {
      "prompt": "Slow cinematic orbit around the bag, studio lighting glinting off the brass zippers, background stays clean, product unchanged.",
      "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

Vous recevez immédiatement un identifiant de tâche :

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

Interrogez ensuite GET /v1/tasks/{taskId} jusqu'à ce que status vaille success, puis téléchargez output[0].url. Voici un script Python complet — le modèle exact utilisé pour générer chaque court métrage de cet article :

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "grok-imagine/image-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    data = json.loads(out)
    if not (data.get("data") or {}).get("taskId"):
        raise RuntimeError(f"submit failed: {out[:300]}")
    return data["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 1200) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=180)

Deux détails opérationnels à surveiller en production :

1. output[0].url est un lien signé à durée limitée (avec une heure d'expiration). Dès qu'une tâche réussit, téléchargez immédiatement les octets et transférez-les vers votre propre stockage — ne conservez jamais durablement l'URL de tâche d'origine.
2. La facturation a lieu au moment où la tâche est acceptée, validez donc avant de soumettre de gros lots. Une astuce utile : envoyez une valeur hors limites, comme "duration": 99 — vous recevrez l'erreur complète de validation du schéma, sans créer de tâche facturable.

Une image statique → un court métrage principal

L'opération la plus courante : prendre une image produit de catalogue et lui donner un mouvement de caméra continu. La photographie produit est par nature statique, le rôle de la consigne est donc d'ajouter uniquement un mouvement crédible, tout en fixant explicitement tout le reste :

Slow cinematic orbit around the burnt-orange canvas weekender bag, camera
circling smoothly from front to three-quarter view, studio lighting glinting
off the brass zippers, seamless white background stays clean and shadowless,
product perfectly sharp and unchanged, subtle premium e-commerce energy.

Sortie réelle — grok-imagine/image-to-video, 6 secondes @ 720p, une seule image de référence. Première génération, non montée. Livré en 960×960 : l'image statique source carrée a pris le pas sur notre demande 9:16 (voir la note sur le rapport d'aspect ci-dessus). L'image statique source est ci-dessous.

Le schéma de consigne pour garder un court métrage produit réaliste :

• Un seul verbe de caméra (« orbite », « rapprochement », « travelling »). Deux mouvements dans une même consigne vous donneront des images à donner le mal de mer.
• Écrivez explicitement « produit inchangé / parfaitement net ». Les modèles image-vers-vidéo dérivent ; indiquer au modèle que le sujet est immuable réduit nettement la déformation des logos, coutures et pièces métalliques.
• Mentionnez le moment matériau (« étincelant sur les fermetures en laiton ») — le reflet qui glisse sur le métal et le cuir est précisément ce qui fait qu'une image statique donne l'impression d'un tournage plutôt que d'une déformation.
• Fixez l'arrière-plan (« reste propre et sans ombre »). Sinon, le modèle invente son propre décor.

Plusieurs images de référence : verrouiller le sujet

image_urls accepte plus d'une image de référence, et c'est précisément là que grok-imagine se distingue des animateurs image par image dans le travail produit. Donnez-lui l'image lifestyle que vous voulez comme scène, plus l'image produit propre comme garantie d'identité : le modèle concilie les deux — la scène vient de la première image, tandis que les garnitures, sangles et fermetures exactes du produit sont ancrées par la seconde :

The same burnt-orange weekender bag rests on a weathered wooden bench in a
sunlit loft; a gentle push-in as dust motes drift through warm window light,
soft shadows slide slowly across the bench, the bag and its dark leather trim
stay exactly consistent with the reference images, calm lifestyle-catalog mood.

Sortie réelle — grok-imagine/image-to-video, 6 secondes @ 720p, 9:16, deux images de référence (image lifestyle sur banc + image produit sur fond blanc). Première génération, non montée.

Remarquez la phrase « cohérent avec les images de référence » dans la consigne — avec plusieurs images de référence, l'exprimer explicitement aide le modèle à traiter les images supplémentaires comme des contraintes d'identité, et non comme une seconde scène à fusionner. C'est le schéma pour les comptes de marque qui publient chaque jour : shooter (ou générer) une image produit par SKU, puis la réutiliser comme point d'ancrage de cohérence dans chaque court métrage lifestyle que vous animez.

Durée et économie du palier brouillon

La durée va de 6 à 30 secondes, et la résolution est le levier budgétaire : le prix par seconde en 480p est environ la moitié de celui en 720p. Comme le fil d'actualité compresse de toute façon agressivement, le pipeline raisonnable consiste à faire un brouillon en 480p, puis remasteriser les gagnants en 720p. Les durées plus longues laissent aussi au modèle la place de dérouler une progression lente — voici un brouillon de 12 secondes en 480p, avec un mouvement d'ambiance continu sur une image statique de boîte à thé :

Moody slow dolly-in on the matte-black tea tin standing on slate, steam curls
up lazily behind it, a soft beam of morning light sweeps across the embossed
label, tiny tea leaves tumble gently onto the slate in the final seconds, dark
premium atmosphere, label text unchanged and legible.

Sortie réelle — grok-imagine/image-to-video, 12 secondes @ 480p, une seule image de référence. Première génération, non montée (livré en carré, comme l'image statique source carrée). Coût : $0.137.

Le rendu en 480p coûte $0.0114/seconde — le court métrage complet de 12 secondes n'a coûté que 13,7 cents. Assez bon marché pour essayer trois variantes de consigne sur chaque produit, en ne payant le tarif 720p que pour la seule que vous publierez réellement. Notez la phrase « texte de l'étiquette inchangé et lisible » dans la consigne : le texte des emballages est la première chose à se brouiller en image-vers-vidéo, et le mentionner est votre protection la moins chère.

Traitement par lots du catalogue

Tout ce qui précède s'étend linéairement, car les tâches sont asynchrones : soumettez d'abord tout le lot, puis interrogez. Un exécuteur de lots minimal pour une liste de produits :

products = [
    {"sku": "weekender-orange", "refs": ["https://cdn.example.com/weekender.jpg"],
     "prompt": "Slow cinematic orbit around the bag, studio light on the brass zippers, background clean, product unchanged."},
    {"sku": "tea-tin-black", "refs": ["https://cdn.example.com/tea-tin.jpg"],
     "prompt": "Moody slow dolly-in, steam drifting, light sweeping the embossed label, label text unchanged."},
    # ... 目录其余部分
]

jobs = []
for p in products:
    tid = submit({
        "prompt": p["prompt"],
        "image_urls": p["refs"],
        "duration": 6,
        "resolution": "480p",     # 草稿档
        "aspect_ratio": "9:16",
    })
    jobs.append((p["sku"], tid))

for sku, tid in jobs:
    task = wait(tid)
    url = task["output"][0]["url"]
    subprocess.run(["curl", "-s", "-o", f"{sku}.mp4", url], timeout=180)
    print(f"{sku}: done")

Conseils pratiques pour exécuter ce pipeline par lots :

• Soumettez d'abord, interrogez ensuite. Chaque rendu prend quelques minutes et s'exécute en parallèle côté serveur ; sérialiser « soumettre-attendre-soumettre » gaspille cette parallélité.
• Gardez un modèle de consigne unique et simple par type de contenu (orbite pour les images produit, rapprochement pour les images lifestyle), puis insérez le nom du produit. La cohérence de l'ensemble du fil d'actualité compte plus que l'ingéniosité de chaque court métrage.
• Vérification du budget : un catalogue de 50 SKU en brouillon 6 s/480p coûte 50 × $0.068 ≈ $3.42. Passer les dix meilleurs en 720p ajoute dix × $0.128 ≈ $1.28. Un mois complet de vidéos produit quotidiennes coûte moins qu'une heure de studio.

Notes de publication pour la vidéo courte

• Le vertical exige une référence verticale. Comme indiqué plus haut, le rapport d'aspect de l'image de référence prend souvent le pas sur aspect_ratio — si le court métrage est destiné au fil d'actualité, recadrez l'image statique en 9:16 avant de soumettre. Recadrer un rendu carré terminé en vertical fera perdre la majeure partie des pixels.
• La première seconde est l'hameçon — les consignes qui font démarrer le mouvement immédiatement (« la caméra orbite », « rapprochement ») surpassent le fondu d'ouverture lent en taux de visionnage complet.
• Les courts métrages s'accompagnent d'une piste d'ambiance générée par le modèle. Chaque sortie que nous générons comporte un flux AAC — certains courts métrages ont une ambiance de studio subtile, d'autres sont presque silencieux. Aucun champ d'entrée ne permet de le contrôler ; lors de la publication, prévoyez donc de le remplacer par votre propre musique ou voix off, plutôt que de le considérer comme une bande-son aboutie.
• Compatibilité avec la lecture en boucle : les orbites et les balayages de lumière bouclent bien mieux que les courts métrages qui se terminent par une révélation. Pour les fils à lecture automatique en boucle (Shorts, Reels), le schéma d'orbite ci-dessus se rejoue sans couture.

Questions fréquentes

Combien de temps prend un rendu ? Les courts métrages de 6 secondes de cet article ont mis quelques minutes chacun à se rendre ; le court métrage de 12 secondes un peu plus longtemps. Traitez-le comme une file asynchrone, et non comme un appel interactif — soumettez par lots et interrogez.

Puis-je utiliser des images générées comme images de référence ? Oui. Les URL de référence doivent simplement être récupérables publiquement. Les trois images statiques sources de cet article sont elles-mêmes des images produit générées par l'API (issues d'exécutions de seedream-5.0-lite), tirées de notre bibliothèque de médias — un pipeline image-statique-vers-vidéo entièrement synthétique.

Et le 1080p ou plus de 30 secondes ? Ce point de terminaison est limité à 720p et 30 secondes. Pour un fil d'actualité vidéo courte, c'est précisément la bonne fourchette ; si vous avez besoin d'une résolution supérieure, agrandissez en post-production ou consultez le catalogue de modèles pour les options actuelles.

En quoi cela diffère-t-il de grok-imagine-1.5/image-to-video ? Le point de terminaison 1.5 preview échange de la plage contre la qualité du mouvement : durée de 1 à 15 secondes, mouvement amélioré, même prix par seconde. Ce point de terminaison 1.0 vous offre 6 à 30 secondes. Nous présentons les bases de la 1.5 dans un autre article détaillé.

Existe-t-il une version texte-vers-vidéo ? Oui — grok-imagine/text-to-video, même interface de tâches, avec seulement une consigne en entrée. Lorsque la cohérence de marque/produit compte, l'image-vers-vidéo est le bon choix ; quand vous devez générer des médias à partir de zéro, utilisez le texte-vers-vidéo.

---

Si vous avez une image produit statique et une clé API, il ne vous reste qu'un POST /v1/tasks pour votre premier court métrage de fil d'actualité : récupérez une clé depuis le tableau de bord, commencez sur la page du modèle grok-imagine/image-to-video, animez une image produit avec la consigne d'orbite ci-dessus — à 13 cents le brouillon, la façon la plus rapide d'apprendre ce modèle est de l'exécuter.