API Kling 4.0 image-vers-vers-vidéo : exemples de requêtes et une exécution réelle

Kling 4.0 image-vers-vers-vidéo transforme une image de première image en un clip de 3 à 30 secondes avec audio synchronisé. Ce guide fournit des exemples de requêtes directement utilisables sur hiapi, les champs acceptés et rejetés par l'API, ainsi que les résultats d'une exécution réelle. Vous devez obtenir une clé API depuis la console hiapi ; l'ID du modèle est kling-4.0/image-to-video, et la page du modèle répertorie les spécifications actuelles.

Si vous utilisez encore Kling 3.0, la présentation de l'API Kling 4.0 a été rédigée avant la sortie et décrit son annonce ; cette page est la référence actuellement disponible.

Requête minimale (curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "prompt": "Elle tourne légèrement la tête vers la caméra, ses cheveux flottent au vent, la caméra avance lentement, bruit des vagues en arrière-plan",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

La réponse renvoie immédiatement un ID de tâche :

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

Interrogez GET /v1/tasks/<taskId> jusqu'à ce que data.status soit success, puis lisez data.output[0].url.

Python : soumission et interrogation

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # exactement une image de première image
            "duration": duration,        # entier, 3-30
            "resolution": resolution,    # "720p" ou "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

Téléchargez immédiatement le fichier MP4 renvoyé. L'URL de sortie comporte un horodatage expireAt (environ sept jours après dans notre exécution) et est hébergée sur un domaine temporaire ; copiez-la donc dans votre propre stockage plutôt que de la lier directement.

Champs acceptés par l'API

Nous avons sondé le point de terminaison avec des valeurs volontairement invalides (ces valeurs renvoient HTTP 400 INVALID_REQUEST et ne créent aucune tâche) :

Champ	Règle observée
image_urls	Tableau obligatoire, exactement un élément (deux éléments → maxItems: got 2, want 1)
duration	Entier, minimum 3, maximum 30. Une chaîne comme "5" est rejetée (got string, want integer)
resolution	720p ou 1080p
aspect_ratio	Facultatif : 16:9, 9:16, 1:1, 21:9. La page du modèle indique que si ce champ est omis, la composition suit l'image source
prompt	Description du mouvement ; nous n'avons envoyé de requêtes sans ce champ que lors des sondes du validateur, considérez-le donc comme recommandé

Deux choses sont source d'erreurs lors de la migration de code depuis d'autres modèles vidéo :

• Le champ est image_urls, et non image_url. Envoyer image_url produit à la fois « champ obligatoire image_urls manquant » et « propriété supplémentaire image_url non autorisée ».
• Il n'existe pas d'interrupteur audio. audio, generate_audio et sound sont tous rejetés comme propriétés supplémentaires. L'audio est toujours généré avec l'image ; guidez l'audio dans le prompt (l'exemple ci-dessus demande le bruit des vagues).

Les champs inconnus sont rejetés plutôt qu'ignorés, de sorte qu'une faute de frappe se manifeste par une erreur 400 au lieu d'un paramètre silencieusement ignoré.

Considérations pour la production

• Privilégiez les callbacks à l'interrogation. La génération d'un clip prend plusieurs minutes ; transmettez donc un callback (contenant url et when: "final") lors de la création de la tâche et traitez le résultat dans le webhook ; n'utilisez l'interrogation qu'en solution de repli.
• Validez avant de payer. Comme les entrées invalides renvoient 400 et ne créent aucune tâche, vérifiez d'abord la durée et la résolution dans votre propre code ; une requête erronée ne coûte rien, mais une requête correcte est facturée pour chaque seconde demandée.
• La facturation est à la seconde et dépend de la résolution. Les clips plus longs et la 1080p coûtent plus cher ; consultez la tarification pour les tarifs actuels plutôt que de vous fier aux chiffres de l'article.
• Conservez l'ID de tâche. Si l'interrogation échoue à cause d'une erreur réseau temporaire, réinterrogez le même ID plutôt que de soumettre à nouveau, sinon un second clip sera créé et facturé.

Exécution mesurée

Nous avons soumis la requête ci-dessus : une image de première image verticale, duration: 3, resolution: "720p", sans aspect_ratio.

• Séquence d'états observée lors d'une interrogation toutes les 10 secondes environ : handling → archiving → success.
• Durée réelle totale : environ 274 secondes pour un clip de 3 secondes. handling représente environ 255 secondes ; planifiez en minutes plutôt qu'en secondes et concevez autour du callback.
• Fichier de sortie (vérifié avec ffprobe) : vidéo H.264, 1280×720, 3,04 secondes, plus une piste audio AAC de même durée. L'audio est donc réellement intégré au MP4, et la composition suit l'image source 16:9.

Nous n'avons pas testé : la 1080p, des durées supérieures à 3 secondes, et des valeurs non par défaut de aspect_ratio. Ces limites proviennent des messages de validation de l'API et de la page du modèle, et non des sorties générées.

Pages associées

• Page du modèle Kling 4.0 image-vers-vidéo
• Page du modèle Kling 4.0 texte-vers-vidéo, pour les cas sans image source
• Page du modèle Kling 3.0 image-vers-vidéo
• Comment utiliser Kling 3.0 Turbo image-vers-vidéo
• Tarification hiapi
• Documentation hiapi

FAQ

Puis-je désactiver l'audio dans Kling 4.0 image-vers-vidéo ?

Pas au moyen d'un champ de requête. audio, generate_audio et sound sont tous rejetés par le validateur. Décrivez dans le prompt le son que vous souhaitez (ou que vous ne souhaitez pas).

Combien d'images d'entrée puis-je envoyer ?

Une seule. image_urls doit contenir exactement une image de première image.

Combien de temps prend une requête ?

Notre clip de 3 secondes en 720p a pris environ 274 secondes de bout en bout. Utilisez des callbacks pour les charges de production.

Quelle est la durée maximale d'un clip ?

L'API accepte duration jusqu'à 30 (secondes entières) et rejette les valeurs supérieures ; nous n'avons personnellement généré que des clips de 3 secondes.