Comment utiliser grok-imagine-1.5/image-to-video via l'API hiapi : curl, Python et une requête directement exécutable

Résumé concis

• De quoi s'agit-il : un guide copiable qui explique comment utiliser grok-imagine-1.5/image-to-video via l'API de tâches unifiée de hiapi pour animer une image statique en une courte vidéo.
• Déroulement : créez une tâche via POST /v1/tasks, interrogez GET /v1/tasks/<taskId> (ou enregistrez un callback), puis téléchargez le MP4 depuis data.output[0].url avant expiration.
• Schéma d'entrée (vérifié contre l'API en ligne) : accepte uniquement une entrée image_urls, un prompt facultatif, duration de 1 à 15 secondes, resolution à 480p/720p, et aspect_ratio parmi auto, 1:1, 16:9, 9:16, 3:2, 2:3. Aucun autre champ n'est accepté.

Ce que vous allez construire et ce qu'il faut préparer

Objectif : envoyer une image source accompagnée d'un prompt de mouvement et obtenir un court clip MP4 généré par Grok Imagine 1.5.

Prérequis :

• Une clé API hiapi—à créer dans le tableau de bord. La clé ressemble à sk-... et se place dans l'en-tête Authorization: Bearer.
• Une URL d'image source accessible publiquement (JPEG/PNG). L'API récupère l'image côté serveur, donc les liens localhost ou les fichiers nécessitant une authentification ne fonctionneront pas.
• N'importe quel client HTTP. Les exemples ci-dessous utilisent curl et requests de Python.

L'id du modèle est la chaîne brute grok-imagine-1.5/image-to-video, sans suffixe.

Exemple minimal exécutable : curl

Créer la tâche :

curl -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/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Une soumission réussie renvoie 200 et un taskId :

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

Interrogez jusqu'à ce que la tâche atteigne un état final (status passe par queued → handling → success ou fail) :

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Tâche terminée (réponse réelle, tronquée) :

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

⚠️ storage: "temp" et expireAt signifient que l'URL de téléchargement est temporaire. Téléchargez le MP4 immédiatement après le succès de la tâche et stockez-le sur votre propre infrastructure—ne faites pas de hotlink.

Exemple minimal exécutable : Python

Script complet—création, interrogation, téléchargement :

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

Référence des entrées (ce que le schéma accepte réellement)

Ces contraintes proviennent directement du validateur en ligne, sans supposition—envoyer autre chose renvoie 400 INVALID_REQUEST avec un message précis :

Champ	Type	Règle
image_urls	tableau de chaînes	Obligatoire, exactement 1 URL (maxItems: 1)
prompt	chaîne	Facultatif—décrivez le mouvement, le mouvement de caméra et l'ambiance
duration	entier	1 à 15 secondes
resolution	chaîne	480p ou 720p
aspect_ratio	chaîne	auto, 1:1, 16:9, 9:16, 3:2, 2:3

Remarques :

• Ce modèle n'a pas de champs seed, negative_prompt, fps, motion_strength ou camera_fixed. Le schéma rejette les propriétés inconnues (additional properties ... not allowed), donc contrôlez entièrement le mouvement et le comportement de la caméra via le prompt.
• Chaque tâche ne peut avoir qu'une seule image de référence. En fournir deux renvoie image_urls: maxItems: got 2, want 1.
• aspect_ratio: "auto" respecte le ratio propre à l'image source—c'est généralement ce que l'on veut pour des photos produit.
• L'ancien grok-imagine/image-to-video accepte jusqu'à 30 secondes par clip ; la version 1.5 est limitée à 15 secondes. Les deux ont le même prix par seconde : $0.015 en 480p et $0.0282 en 720p.

Considérations pour la production

Utilisez un callback au lieu du polling. Pour tout cas au-delà d'un script, enregistrez un webhook lors de la création de la tâche et évitez la boucle de polling :

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url doit être un endpoint http(s) public, et when ne prend en charge que "final"—vous recevez un POST unique lorsque la tâche atteint success ou fail. Le polling convient aux CLI et aux tâches par lots ; les callbacks sont préférables lorsque vous devez générer de nombreux clips en masse sans déployer une armée de pollers. Conservez un polling de secours (par exemple, vérifier toutes les quelques minutes les tâches n'ayant pas reçu de callback) pour éviter qu'un webhook perdu ne laisse une tâche bloquée.

Idempotence. La création de tâche n'est pas dédupliquée côté serveur, donc une simple nouvelle tentative après un timeout réseau peut entraîner des soumissions et des facturations en double. Persistez le taskId immédiatement après le retour de l'appel de création, et vérifiez votre propre stockage avant de réessayer ; si vous plantez entre la soumission et la persistance, listez les tâches récentes (GET /v1/tasks) et faites correspondre par modèle + heure de création avant de soumettre à nouveau.

Gestion des erreurs. Les modes de défaillance que vous rencontrerez réellement :

• 401 avec {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}—clé incorrecte, ou clé sans accès à ce modèle. La réponse contient un request_id pour le support.
• 400 avec error_code: "INVALID_REQUEST"—violation de schéma ; message indique le champ et la règle précis (par exemple duration: maximum: got 99, want 15). Corrigez le corps de la requête, ne réessayez pas à l'aveugle.
• 402 solde insuffisant—les modèles vidéo prévérifient votre quota à la soumission. Rechargez puis soumettez à nouveau.
• La tâche elle-même renvoie status: "fail"—échec côté génération ; inspectez data.error et réessayez avec un backoff. Une image source inaccessible en est une cause fréquente.

Stockez la sortie immédiatement. Cela vaut la peine d'être répété : output[0].url réside sur un stockage temporaire avec un horodatage expireAt. Dès que vous voyez success, streamez immédiatement le MP4 vers votre propre bucket de stockage. Si votre pipeline plante après le succès mais avant le téléchargement, récupérez à nouveau la tâche par id—l'URL reste valide jusqu'à expireAt, mais pas éternellement.

Lectures complémentaires

• Page du modèle grok-imagine-1.5/image-to-video—tarification, paramètres et playground dans le navigateur
• Comment utiliser grok-imagine/image-to-video—le modèle précédent, même flux de tâches, limite de 30 secondes
• Guide de Grok Imagine texte-vers-vidéo—partir d'un prompt plutôt que d'une image
• Référence de l'API hiapi—contrat complet de l'API de tâches

Questions fréquentes

Quelle peut être la durée d'une vidéo grok-imagine-1.5 ? De 1 à 15 secondes, définie par le champ entier duration. Une demande plus longue renvoie 400 (duration: maximum: got X, want 15). Si vous avez besoin de jusqu'à 30 secondes, utilisez l'ancien grok-imagine/image-to-video.

Quelles résolutions et quels ratios d'aspect sont pris en charge ? resolution vaut 480p ou 720p ; aspect_ratio vaut auto, 1:1, 16:9, 9:16, 3:2 ou 2:3. 9:16 en 720p est la combinaison privilégiée pour les clips verticaux de style Shorts/Reels.

Puis-je fournir plusieurs images de référence ? Non—image_urls de ce modèle n'accepte exactement qu'une seule URL. Pour les workflows à références multiples, enchaînez les tâches ou composez d'abord les images de référence en une seule image d'entrée.

Y a-t-il un seed ou un prompt négatif ? Non. Le schéma d'entrée rejette directement seed, negative_prompt, fps et champs similaires. Le style de mouvement, le mouvement de caméra et l'ambiance sont tous contrôlés par la chaîne prompt.

Combien cela coûte-t-il ? La facturation se fait à la seconde de vidéo générée : $0.015/seconde en 480p, $0.0282/seconde en 720p. Un clip de 6 secondes coûte $0.09 en 480p et $0.1692 en 720p. Si duration n'est pas fourni, la valeur par défaut est de 8 secondes. Voir d'autres exemples dans le détail tarifaire de Grok Imagine 1.5.

Pourquoi ma requête renvoie-t-elle 401 permission_denied ? Soit la clé API est incorrecte/révoquée, soit elle n'a pas accès à ce modèle. Vérifiez la clé dans le tableau de bord et assurez-vous d'envoyer Authorization: Bearer sk-...—l'absence du préfixe Bearer produit la même erreur.

Comment savoir que la vidéo est prête sans polling ? Ajoutez "callback": {"url": "https://your-endpoint", "when": "final"} à la création de la tâche. Une fois la tâche dans un état final, hiapi envoie un POST à votre endpoint. En secours, interrogez GET /v1/tasks/<taskId>.

Pourquoi l'URL de ma vidéo cesse-t-elle de fonctionner après quelques jours ? La sortie réside sur un stockage temporaire—chaque entrée de sortie porte un horodatage expireAt. Téléchargez le fichier immédiatement après success et servez-le depuis votre propre stockage.