API image-vers-voix Kling 3.0 Turbo en Python : schéma, script complet et gestion des erreurs

Le schéma de kling-3.0-turbo/image-to-video est compact et strict : une URL d'image publique, une invite de mouvement obligatoire, une durée entière de 3 à 15 secondes et une sortie en 720p ou 1080p. Cette page est la référence propre à cette version : elle sert à valider ce corps de requête et à distinguer une erreur HTTP 400 d'un résultat asynchrone TASK_FAILED.

Pour le flux générique de création, d'interrogation répétée, de rappel et de téléchargement, consultez le guide du lanceur de tâches Python Kling et du choix Omni/Turbo.

Schéma d'entrée de Turbo

Champ	Type	Obligatoire	Valeurs acceptées
prompt	string	Oui	Décrit le mouvement et le comportement de la caméra
image_urls	tableau de chaînes	Oui	Exactement une URL d'image accessible publiquement
duration	integer	Non	3 à 15 secondes
resolution	string	Non	720p ou 1080p

Turbo n'accepte ni sound, ni aspect_ratio, ni negative_prompt, ni seed, ni mode, ni une seconde URL d'image. Le schéma strict rejette les propriétés supplémentaires au lieu de les ignorer silencieusement.

L'image d'entrée détermine la forme du cadre. Avant de créer la tâche, téléversez-la dans un bucket public ou sur un CDN ; le moteur de rendu ne peut pas récupérer localhost, les tableaux de bord privés ni les URL signées expirées.

Requête minimale fonctionnelle

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

Une réponse réussie contient data.taskId. Un HTTP 200 signifie seulement que la création a réussi, et non que le rendu est terminé ; le rendu de la vidéo se poursuit de façon asynchrone.

Prévalidation en Python

Validez les contraintes avant l'appel réseau, afin que les erreurs évidentes ne créent jamais de tâche :

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

Cette vérification locale détecte les problèmes de forme des valeurs, mais ne prouve pas que l'image distante peut être téléchargée publiquement. Le moteur de rendu effectue cette récupération après la création de la tâche.

Script Python complet : soumission, interrogation répétée, téléchargement

L'extrait ci-dessus s'arrête à l'ID de tâche. Cette version exécute le travail complet et enregistre le MP4. Elle envoie l'en-tête Idempotency-Key, de sorte qu'une nouvelle tentative de la même soumission après un délai d'attente renvoie la tâche d'origine au lieu de créer et facturer une seconde tâche :

import os
import time
import uuid

import requests

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


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

Un tel clip de 5 secondes en 720p coûte 0,65 $. En production, remplacez la boucle d'interrogation répétée par "callback": {"url": "https://your-app.example.com/hiapi/callback"} au niveau supérieur, et dédupliquez les notifications par ID de tâche.

HTTP 400 : la tâche n'a jamais été créée

Une réponse HTTP 400 résulte d'une validation synchrone du schéma. Les causes typiques sont les suivantes :

Entrée invalide	Cause de l'échec	Correction
"duration": "5"	Une chaîne a été envoyée au lieu d'un entier	Envoyez 5
"duration": 20	La valeur maximale est 15	Choisissez entre 3 et 15
Deux image_urls	Turbo n'en accepte qu'une	Ne conservez que l'image de départ
"resolution": "4K"	Turbo prend en charge 720p et 1080p	Utilisez 720p ou 1080p, ou choisissez Omni
"sound": true	sound ne fait pas partie du schéma Turbo	Supprimez ce champ ou choisissez Omni
prompt manquant	Turbo exige une invite	Ajoutez une invite de mouvement non vide

Comme la validation échoue avant la création, aucun ID de tâche n'est disponible pour l'interrogation répétée. Consignez le corps de la réponse et l'ID de requête, corrigez le corps de la requête, puis soumettez une nouvelle requête.

TASK_FAILED : création réussie, mais rendu échoué

Si POST /v1/tasks renvoie un HTTP 200 avec un ID de tâche, l'échec ultérieur relève du cycle de vie asynchrone de la tâche et doit être traité différemment d'une erreur 400.

Les causes courantes sont notamment :

• l'URL de l'image exige un Cookie ou un en-tête d'autorisation ;
• l'URL d'image signée a expiré avant la récupération par le moteur de rendu ;
• l'hôte bloque la récupération côté serveur, ou redirige vers une page HTML ;
• le fichier est corrompu, ou son type MIME ne correspond pas à son contenu ;
• le fournisseur n'a pas pu terminer ce rendu.

Consignez l'ID de tâche, le code et le message d'erreur finaux, l'URL d'entrée d'origine et l'horodatage de la requête. Avant de réessayer, vérifiez qu'un serveur non authentifié peut récupérer cette image avec une réponse 2xx et un type de contenu d'image. Réessayer aveuglément la même URL inaccessible ne fera que créer une nouvelle tâche en échec.

Le guide Python générique contient la boucle commune d'interrogation répétée jusqu'à l'état terminal et le code de téléchargement de la sortie ; les y laisser évite de répéter la logique de cycle de vie sur cette page de référence de version.

Tarification et choix du modèle Turbo

Les tarifs de production actuels sont les suivants :

Palier Turbo	Prix par seconde	Tâche de 5 secondes
720p	0,130 $	0,65 $
1080p	0,160 $	0,80 $

Avant une utilisation à grande échelle, consultez la page de tarification à jour. Le nom Turbo désigne une variante de modèle et ne garantit ni un prix inférieur à chaque résolution, ni le respect d'un SLA de temps de rendu fixe pour les tâches.

Lorsque vous avez besoin d'une image de fin, d'audio ou de 4K, choisissez Kling 3.0 standard (kling-3.0/image-to-video) : il accepte une ou deux images (image de départ et image de fin), dispose d'un commutateur sound, et coûte 0,10 $/s en 720p sans audio et 0,129 $/s en 1080p sans audio. Lorsque vous avez besoin d'images ou de vidéos de référence, choisissez Omni. Pour une seule image d'entrée en 720p ou 1080p, comparez ces variantes avec vos propres invites de mouvement, et évaluez la qualité de sortie, le temps d'attente en file et le coût total.

Questions fréquentes

Combien d'images l'API image-vers-voix Kling 3.0 Turbo accepte-t-elle ?

Exactement une URL d'image publique. Une seconde image déclenche une erreur de schéma (image_urls: maxItems: got 2, want 1) ; pour un contrôle par image de départ et de fin, utilisez l'API image-vers-voix Kling 3.0 standard.

Quelles valeurs de durée sont valides ?

Envoyez un entier de 3 à 15. Un nombre entre guillemets comme "5" est une chaîne et échouera à la validation.

Turbo prend-il en charge la 4K ou l'audio ?

Pas de 4K : ce point de terminaison accepte 720p ou 1080p. Il n'y a pas de champ sound, mais les clips Turbo comportent leur propre audio, qui ne peut pas être désactivé. Lorsque vous avez besoin de 4K ou d'une sortie silencieuse, utilisez Kling 3.0 standard ou Omni.

Quelle est la différence entre HTTP 400 et TASK_FAILED ?

HTTP 400 signifie que la requête enfreint le schéma, donc aucune tâche n'a été créée. TASK_FAILED survient après une réponse de création valide, lors de la récupération de l'entrée ou de la génération.

Pourquoi une URL d'image apparemment publique provoque-t-elle un TASK_FAILED ?

L'URL peut dépendre de Cookies, avoir une signature expirée, bloquer la récupération côté serveur, ou renvoyer du HTML au lieu des octets de l'image. Avant de réessayer, testez-la sans authentification de navigateur.