API Kling AI image-vers-image en Python

Utilisez l'API Kling AI image-vers-vidéo en Python via le point de terminaison de tâches asynchrones de HiAPI. Le démarrage rapide ci-dessous utilise l'ID de modèle actuellement appelable kling-3.0-omni/image-to-video, interroge la tâche jusqu'à un état terminal et télécharge le MP4 généré.

Pour consulter les champs exacts, ouvrez la documentation de l'API Kling 3.0 Omni image-vers-vidéo. Utilisez la page du modèle Omni actuel pour voir le modèle et le Playground, et vérifiez les tarifs Kling API en temps réel avant toute exécution en production.

Démarrage rapide : exécuter Kling image-vers-vidéo en Python

Installez requests avec python -m pip install requests, définissez HIAPI_API_KEY dans votre environnement et remplacez IMAGE_URL par une URL publique JPEG, PNG ou WebP. Le script complet correspond au premier bloc de code copiable :

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

La requête de création renvoie un taskId sans attendre la fin de la génération de la vidéo. Le script interroge GET /v1/tasks/{taskId}, s'arrête sur success ou fail et télécharge la première sortie dès que possible, car l'URL de résultat expire.

Ouvrez le modèle Kling Omni et essayez ce payload.

Choisir le modèle Kling image-vers-vidéo actuellement disponible

ID du modèle	Cas d'usage	Conventions d'entrée et de sortie
kling-3.0-omni/image-to-video	Nécessite un contrôle première/dernière image, un son natif optionnel ou la 4K	Une à deux URL d'images publiques ; 3-15 secondes ; 720p, 1080p ou 4K
kling-3.0-turbo/image-to-video	Une seule image de départ suffit et un schéma plus simple en 720p/1080p répond au besoin	Exactement une URL d'image publique ; prompt obligatoire ; 3-15 secondes ; 720p ou 1080p

La référence complète des champs Omni se trouve dans la documentation Omni I2V. Turbo dispose d'une référence de schéma Turbo I2V distincte. Les deux utilisent le même flux de création et d'interrogation via /v1/tasks, vous pouvez donc conserver un seul exécuteur et ne remplacer que model et input.

Un corps de requête conforme aux exigences du modèle

Omni avec première et dernière image

Envoyez une URL pour la première image, ou deux URL dans l'ordre [first, last] :

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni accepte un ou deux image_urls. Son prompt est optionnel, duration est un entier de 3 à 15, resolution vaut 720p, 1080p ou 4K, et sound est optionnel.

Turbo avec une image de départ

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo exige un prompt et exactement une entrée dans image_urls. N'envoyez pas de champs réservés à Omni (par exemple sound) et n'ajoutez pas de champs texte-vers-vidéo (par exemple aspect_ratio) ; l'image est déterminée par l'image source.

Tarifs Kling AI : utilisez les paliers en temps réel, ne recopiez pas les prix

Les tarifs Kling AI sur HiAPI sont facturés à l'usage. Actuellement, les deux modèles image-vers-vidéo facturent à la seconde générée, avec un taux précis déterminé par le modèle et la résolution ; Omni propose en outre différents paliers selon l'activation de l'audio. Des clips plus longs, une résolution plus élevée ou un son natif modifient le coût de la tâche.

Les tarifs pouvant changer, ce guide ne fixe pas de grille de prix en dollars. Avant d'établir un budget ou de soumettre un lot important de tâches, consultez immédiatement le tableau des tarifs modèles en temps réel.

Kling AI est-il gratuit ?

Non : sur HiAPI, la génération via l'API Kling image-vers-vidéo n'est pas une API gratuite et illimitée. Les tâches réussies consomment le solde au taux en temps réel du modèle, de la durée, de la résolution et des paramètres audio choisis. Les promotions de compte ou les récompenses pour nouveaux utilisateurs peuvent changer et être soumises à conditions ; ne les considérez donc pas comme un niveau gratuit Kling garanti. Avant de soumettre une tâche, vérifiez les offres en vigueur et votre solde dans votre compte.

Contrôles de production pour éviter les échecs ou les doublons de tâches

1. Utilisez des URL d'images HTTPS directement téléchargeables. localhost, les pages nécessitant une connexion, les pages de partage HTML et les URL signées expirées peuvent échouer après la création de la tâche.
2. Enregistrez le taskId avant de relancer un worker. Une nouvelle tentative de l'appel de création peut créer et facturer une seconde tâche.
3. Considérez success et fail comme des états terminaux. En production, utilisez le callback.url de premier niveau et conservez l'interrogation comme filet de sécurité de réconciliation.
4. Téléchargez rapidement output[].url et copiez les résultats à conserver durablement dans un stockage que vous contrôlez.
5. Validez le schéma du modèle choisi avant l'envoi. Les conventions strictes des modèles rejettent les champs inconnus.

Erreurs courantes

• HTTP 400 : la requête ne correspond pas au schéma ; vérifiez le champ indiqué, les valeurs d'énumération, la longueur du tableau et le type JSON.
• HTTP 401 : la clé bearer est absente, invalide ou ne peut pas utiliser le modèle choisi.
• La tâche passe à fail : la requête de création a passé la validation, mais le moteur de rendu n'a pas pu récupérer l'entrée ou terminer la génération. Enregistrez le taskId et l'erreur renvoyée séparément de la réponse de création.
• L'URL de sortie a expiré : le rendu a peut-être réussi, mais l'URL de récupération temporaire n'a pas été téléchargée à temps.

Questions fréquentes

Quel modèle Kling image-vers-vidéo utiliser en Python ?

Utilisez kling-3.0-omni/image-to-video lorsque vous avez besoin d'un contrôle sur une ou deux images, d'un son natif optionnel ou de la 4K. Utilisez kling-3.0-turbo/image-to-video lorsqu'une image de départ et une sortie 720p/1080p suffisent. Le code Python de création, d'interrogation et de téléchargement reste identique.

Quels sont les ID actuels des modèles Kling AI image-vers-vidéo ?

Les ID actuellement appelables couverts dans cet article sont kling-3.0-omni/image-to-video et kling-3.0-turbo/image-to-video. Envoyez l'un ou l'autre dans le champ model de premier niveau de POST /v1/tasks.

Combien d'images Kling image-vers-vidéo accepte-t-il ?

Omni accepte une image comme première image, ou deux images dans l'ordre [first, last]. Turbo accepte exactement une image de départ.

Combien coûte l'API Kling AI ?

La facturation se fait à la seconde générée. Le taux exact en temps réel dépend du modèle et de la résolution, et pour Omni également des paramètres audio. Utilisez la page des tarifs en temps réel et ne recopiez pas de prix statiques depuis ce guide.

Kling AI est-il gratuit via l'API ?

Aucun niveau gratuit illimité de l'API Kling n'est garanti. La génération consomme le solde du compte au taux en temps réel des tâches. Vérifiez dans votre compte si une offre de démarrage conditionnelle est en cours, plutôt que de supposer un quota gratuit fixe.

Pourquoi une tâche échoue-t-elle alors que la requête de création a réussi ?

Le JSON a passé la validation initiale, mais le moteur de rendu n'a peut-être pas pu récupérer l'image ou terminer la génération. Vérifiez que l'image est publique et non expirée, puis consultez l'erreur terminale à partir du taskId enregistré.

Comment récupérer la vidéo générée ?

Lisez data.taskId dans la réponse de création. Un script local peut interroger GET /v1/tasks/{taskId} ; en production, vous pouvez utiliser callback.url. En cas de success, téléchargez data.output[0].url avant son expiration.

Lisez ensuite la référence complète de l'API Kling Omni, puis ouvrez la page du modèle actuel lorsque vous êtes prêt à tester une requête.