Contrôle de la première et de la dernière image dans les vidéos IA : guide du mouvement précis entre modèles sur hiapi

La plupart des API de génération de vidéo à partir d'image n'acceptent qu'une seule image fixe, puis improvisent le mouvement. Seuls quelques modèles vous permettent de verrouiller le point d'arrivée du plan, et pas seulement son point de départ — vous fournissez une première et une dernière image, et le modèle interpole le mouvement entre les deux. C'est précisément la différence entre « faire bouger cette photo » et « réaliser exactement cette transition ».

Le problème : la prise en charge du contrôle de la dernière image n'est pas homogène d'un modèle à l'autre, et même au sein de la gamme d'un même fournisseur, les paliers phare et rapide/turbo peuvent différer. Ce tutoriel précise clairement quels modèles vidéo hiapi ne prennent en charge que la première image, lesquels prennent en charge première + dernière image, et donne pour chacun les champs d'entrée réels (et non uniformes), afin que vous ne découvriez pas, après bien des efforts, que le modèle choisi ignore silencieusement votre dernière image.

1. Ce dont vous avez besoin

Une clé API hiapi provenant de la console (sk-...), ainsi que deux URL d'images accessibles par le modèle cible (URL HTTPS publiques — le point de terminaison des tâches ne prend pas en charge l'envoi de fichiers locaux). Chacun des modèles ci-dessous s'appelle via la même API de tâches unifiée, donc si votre clé fonctionne pour l'un, elle fonctionne pour tous.

2. Exemple minimal exécutable

Toute génération de vidéo hiapi passe par le même point de terminaison : créer une tâche, puis l'interroger (ou utiliser un callback — voir les modèles de production) jusqu'à atteindre un état terminal.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video est l'exemple le plus typique de ce mode : input.image_urls accepte une ou deux URL d'images. Avec une seule, le modèle n'ancre que la première image et laisse le reste libre ; avec deux, la seconde URL devient la dernière image imposée — le modèle reçoit l'instruction de terminer le plan à cet endroit. La durée est un entier de 3 à 15 (secondes), resolution vaut 720p / 1080p / 4k, et un booléen sound optionnel ajoute une ambiance audio générée. Il n'y a pas de champ aspect_ratio ici — le format de sortie suit les images fournies.

Tous les modèles ne suivent pas cette structure. seedance-2.5/image-to-video obtient le même résultat via deux champs nommés séparément plutôt qu'un tableau :

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url n'a de sens qu'en paire avec first_frame_url — vous pouvez envoyer uniquement first_frame_url pour un plan à première image seule, mais pas l'inverse. Ce modèle accepte une durée de 4 à 30 s, une résolution allant au plus haut à 720p/1080p (pas de palier 4K), et aspect_ratio vaut adaptive par défaut, c'est-à-dire qu'il suit la première image plutôt qu'une valeur explicite 16:9/9:16.

Les noms de champs diffèrent réellement selon les modèles — image_urls contre first_frame_url/last_frame_url — donc chaque changement de modèle doit être considéré comme un changement de schéma, et non comme un simple remplacement direct.

Tous les modèles ne le prennent pas en charge

veo-3.1/image-to-video accepte une seule chaîne image_url, sans aucun paramètre de dernière image — vous pouvez définir aspect_ratio (auto/16:9/9:16), resolution, ainsi qu'une énumération fixe de duration (4, 6 ou 8 secondes), mais vous ne pouvez pas verrouiller l'image finale. La gamme Kling un cran en dessous est dans le même cas : kling-3.0-turbo/image-to-video (la version rapide/économique de kling-3.0-omni) n'accepte qu'un seul élément au maximum dans image_urls — pas de dernière image, et pas de résolution 4K. Si vous avez besoin du contrôle de la dernière image, choisissez le palier phare ou un modèle conçu pour cela (comme seedance-2.5), plutôt que de vous fier au nom de la famille de modèles.

3. Modèles de production

À grande échelle, utilisez des callbacks plutôt que l'interrogation. Passez un objet callback dans le même corps de requête, au lieu d'interroger en boucle :

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" ne se déclenche qu'une fois, lorsque la tâche atteint l'un de ses états terminaux — succeeded ou failed sont tous deux terminaux, donc votre gestionnaire de webhook doit dédupliquer par taskId plutôt que de supposer qu'un callback signifie toujours un succès. L'interrogation via GET /v1/tasks/:id convient mieux au débogage local, aux appels ponctuels à faible fréquence, ou comme filet de sécurité de réconciliation lorsqu'un callback n'arrive jamais (instabilité réseau, votre point de terminaison brièvement hors ligne).

Idempotence. Une nouvelle tentative après un délai d'attente ou une connexion interrompue peut, si l'on n'y prend pas garde, créer des tâches en double — enregistrez l'id de tâche renvoyé par l'appel de création et, avant d'envisager de soumettre une nouvelle tâche, effectuez un GET sur cet id en guise de nouvelle tentative.

Les URL de sortie expirent. Le champ expireAt présent sur chaque entrée de sortie n'est pas décoratif — que vous soyez informé du succès de la tâche par callback ou par interrogation, téléchargez la vidéo dès que possible et persistez-la (dans votre propre stockage).

Échec d'authentification. Une clé erronée ou absente renvoie HTTP 401 avec {"error": {"code": "permission_denied", ...}}. Vérifiez explicitement ce statut/ce code d'erreur, plutôt que de supposer que tout code non-2xx signifie un échec de la génération elle-même — il est utile de distinguer dans votre gestion d'erreurs « ma clé est incorrecte » de « le modèle a rejeté mon entrée », car les corrections sont totalement différentes.

4. Pages associées

• Page du modèle Kling 3.0 Omni image-to-video — tarification, essai en ligne et référence complète des paramètres du modèle utilisé dans les exemples ci-dessus.
• Page du modèle Seedance 2.5 image-to-video — la variante first_frame_url/last_frame_url.
• Documentation d'authentification — fonctionnement de l'en-tête Authorization: Bearer sk-... et des portées de clé.
• Documentation de création de tâche — référence complète requête/réponse de /v1/tasks, y compris les options de callback.
• Tarification hiapi — tarifs actuels à la seconde et selon la résolution (la facturation varie selon le modèle et la résolution ; consultez la page en temps réel plutôt que des chiffres figés).

5. Questions fréquentes

Quels modèles vidéo hiapi prennent en charge le contrôle de la dernière image ? kling-3.0-omni/image-to-video (via un tableau image_urls à 2 éléments) et seedance-2.5/image-to-video (via first_frame_url + last_frame_url) le prennent en charge actuellement. veo-3.1/image-to-video et kling-3.0-turbo/image-to-video ne le prennent pas en charge — ils n'acceptent qu'une seule image de départ.

Peut-on spécifier uniquement la dernière image sans fournir de prompt ? Les deux modèles acceptent toujours (et attendent généralement) un prompt en plus des images — il guide le mouvement entre les deux images, pas seulement le contenu. Tous les modèles ne rejettent pas explicitement un prompt vide ou absent, mais décrire explicitement la transition rend le mouvement plus prévisible.

Les deux images doivent-elles avoir le même rapport hauteur/largeur ? Ni kling-3.0-omni/image-to-video ni seedance-2.5/image-to-video ne proposent de aspect_ratio explicite indépendant des images — le format de sortie suit les images d'entrée, donc des rapports hauteur/largeur incohérents entre la première et la dernière image produiront un résultat visiblement bancal plutôt qu'une erreur. Avant de soumettre, recadrez ou complétez les deux images pour qu'elles aient le même rapport.

Que se passe-t-il si l'on n'envoie que la dernière image sans la première ? Les deux modèles ne le prennent pas en charge — sur seedance-2.5, last_frame_url ne s'utilise qu'avec first_frame_url ; le tableau de kling-3.0-omni est lu par position (premier élément = première image). Il n'existe pas de mode « inverse » où l'on ne spécifierait que l'image finale.

Le contrôle de la dernière image équivaut-il au transfert de mouvement vidéo-vers-vidéo ? Non — c'est une autre capacité (sur hiapi, seedance-2.5/reference-to-video, qui prend une vidéo de référence pour piloter le mouvement ou le mouvement de caméra, et non deux images fixes). Le contrôle première/dernière image interpole entre deux images ; la vidéo-vers-vidéo par référence imite le schéma de mouvement d'un clip existant.

Ajouter une dernière image coûte-t-il plus cher qu'une génération à première image seule ? Les deux modèles facturent à la seconde et selon la résolution, et non selon les images d'entrée, donc ajouter une dernière image n'augmente pas le coût en soi — consultez la page de tarification pour les tarifs actuels.