Comment appeler l'API de génération de vidéo à partir de texte Kling 2.5 Turbo : guide curl et Python

Ce que le point de terminaison kling-2.5-turbo/text-to-video vous offre

kling-2.5-turbo/text-to-video est le modèle de génération de vidéo à partir de texte proposé sur HiAPI. Vous lui donnez une invite textuelle, et il renvoie une vidéo générée. Le terme « turbo » dans le nom indique l'axe d'optimisation : un délai d'exécution plus rapide que le niveau de qualité standard, au prix d'une perte de détails. Pour les rendus de brouillon, les aperçus de storyboard, les montages pour réseaux sociaux et l'itération créative, ce compromis est généralement le bon.

Avant d'écrire la première ligne de code, le point le plus important à intégrer est celui-ci : il s'agit d'un point de terminaison asynchrone. La génération vidéo prend de quelques secondes à plusieurs minutes, bien au-delà de tout délai d'expiration HTTP raisonnable. L'API est donc divisée en deux opérations :

1. Soumission — vous envoyez en POST l'invite et les paramètres, et récupérez immédiatement un identifiant de tâche.
2. Interrogation — vous envoyez à plusieurs reprises une requête GET sur la tâche avec cet identifiant, jusqu'à ce qu'elle atteigne un état terminal, puis vous lisez le résultat vidéo dans la charge utile de la réponse finalisée.

Si vous tentez de la modéliser comme un appel bloquant, vous rencontrerez des délais d'expiration, des générations en double lors des nouvelles tentatives et des réinitialisations de connexion sous forte charge. Le modèle soumettre puis interroger n'est pas une contrainte à contourner ; c'est le bon modèle mental. Chaque exemple de code ci-dessous est construit autour de lui, et une fois ce point intégré, le reste de l'intégration est direct.

Il faut aussi fixer une attente : le point de terminaison est à état, mais l'état réside côté serveur, pas chez vous. Les tâches existent indépendamment de votre connexion HTTP. Votre script peut planter en cours d'interrogation, redémarrer, puis reprendre la même tâche avec l'identifiant — à condition que vous ayez persisté cet identifiant quelque part. Concevez dès le départ dans cet esprit.

Structure de la requête : invite, préréglage rapide et durée flexible

Vous ne contrôlez que quelques champs, mais chacun a un impact réel sur la tâche. Voici ce qui compte vraiment.

Invite

L'invite est l'entrée créative principale. Traitez-la comme une description de plan, pas comme une requête de recherche. Une bonne invite pour ce modèle inclut généralement :

• Le sujet — qui ou quoi est à l'écran.
• L'action — ce que fait le sujet dans le clip.
• La caméra — le cadrage et le mouvement, par exemple slow dolly in, static wide shot, handheld follow.
• L'environnement et la lumière — le décor, le moment de la journée, l'ambiance.
• Le style — si vous voulez orienter le rendu, vous pouvez écrire cinematic, anime, product photography, etc.

Restez concret et placez le sujet en premier. Une invite vague produit un mouvement vague, et le niveau turbo amplifie cet effet, car il laisse moins de place à l'interprétation.

Préréglage fast/turbo

La famille de modèles prend en charge un préréglage rapide qui échange une partie de la finesse contre de la latence. Lorsque vous l'activez, vous demandez au backend de privilégier la vitesse — le mouvement reste cohérent, mais les textures fines, les petits visages et les arrière-plans complexes se dégradent plus tôt que dans le parcours qualité. Utilisez-le dans votre boucle d'itération pour tester des variantes d'invite ; lorsque vous rendez finalement le plan principal, réfléchissez à si le parcours qualité constitue une meilleure dernière étape. Le préréglage est un champ de requête, donc une décision par tâche, pas un réglage global au niveau du compte.

Durée flexible

La durée est flexible dans la plage prise en charge par le modèle, et non fixée à une longueur unique. Une durée plus longue implique de générer plus d'images, donc un temps d'achèvement plus long et un coût plus élevé — la facturation est calculée à la seconde de sortie. Choisissez la durée la plus courte qui satisfait le plan. Une boucle de cinq secondes pour une publication sur réseaux sociaux n'a pas besoin de la même longueur qu'un temps narratif.

Discipline des champs

Ne définissez que les champs dont vous avez besoin. Les clés inconnues ou mal orthographiées sont une source courante de configuration silencieusement erronée, alors gardez le corps de requête JSON petit, explicite, et versionnez-le avec le reste de la configuration de votre pipeline.

Lancer une requête avec curl

Chaque appel HiAPI utilise le même schéma d'authentification : un jeton bearer dans l'en-tête Authorization. Placez la clé dans une variable d'environnement, pour qu'elle n'apparaisse pas dans l'historique du shell ou dans un script validé.

export HIAPI_API_KEY="your_api_key_here"

Puis soumettez la tâche. Les noms de champs et le chemin exacts du point de terminaison doivent être tirés de la référence du modèle ; la forme ci-dessous est la forme canonique :

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "prompt": "A slow dolly-in on a ceramic coffee cup on a wooden table, morning light raking across the surface, steam rising, shallow depth of field, cinematic",
    "duration": 5,
    "fast": true
  }'

Vous devez vous attendre à recevoir non pas une vidéo, mais une confirmation contenant l'identifiant de la tâche et son état initial — généralement l'état queued ou processing, plus un champ id. Enregistrez cet ID ; c'est le handle de toutes les opérations suivantes.

La réponse minimale ressemble à ceci :

{
  "id": "job_abc123",
  "status": "queued",
  "model": "kling-2.5-turbo/text-to-video"
}

L'appel de soumission doit revenir rapidement — bien moins d'une seconde dans des conditions normales. S'il reste suspendu, le problème vient de la connectivité ou de l'authentification, pas du modèle. Si vous recevez 401, vérifiez le format de l'en-tête (le préfixe Bearer est important). Si vous recevez 422, votre corps de requête JSON est mal formé ou il manque un champ obligatoire.

N'ajoutez pas -L, de nouvelles tentatives ni de long délai d'expiration à cet appel. L'étape de soumission réussit rapidement ou échoue rapidement. Toute l'attente se produit dans la boucle d'interrogation, dont nous parlons ensuite.

La même requête en Python

La version Python est une fine enveloppe autour du même contrat HTTP. Utilisez requests avec une Session partagée, pour que le pool de connexions soit effectif entre la soumission et chaque interrogation. Enveloppez-la dans une fonction, pour que le reste de votre code ne touche jamais directement au HTTP brut.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

session = requests.Session()

def submit_video(prompt: str, duration: int = 5, fast: bool = True) -> str:
    body = {
        "model": "kling-2.5-turbo/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "fast": fast,
    }
    resp = session.post(f"{BASE}/video/generations", json=body, headers=HEADERS, timeout=15)
    resp.raise_for_status()
    return resp.json()["id"]

def poll_video(job_id: str, timeout_s: int = 600, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = session.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed", "cancelled"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    job = submit_video("A slow dolly-in on a ceramic coffee cup, morning light, steam rising, cinematic")
    result = poll_video(job)
    print(result)

Quelques détails méritent d'être conservés plutôt que simplifiés : le timeout sur chaque requête, pour qu'un socket bloqué ne suspende pas votre worker ; le recul exponentiel avec une limite raisonnable ; et un TimeoutError distinct, pour que l'appelant puisse distinguer « toujours en cours » de « cassé ».

Si vous préférez httpx, la conversion est directe — mêmes méthodes, URL et corps de requête JSON. La couche de transport n'est pas la partie intéressante ; le contrat l'est. Avant de commencer l'interrogation, stockez le job_id dans un emplacement persistant, pour qu'un redémarrage n'orpheline pas une génération en cours.

Interroger la tâche et lire la réponse

La boucle d'interrogation est le lieu de la plupart des bugs d'intégration. Trois règles la rendent fiable.

Règle 1 : seuls les états terminaux mettent fin à la boucle

Vous verrez des états transitoires — queued, processing — et des états terminaux comme succeeded, failed et cancelled. Seuls les états terminaux font sortir de la boucle. Ne traitez pas une chaîne d'état inconnue comme un succès, et n'interrompez pas sur processing. Journalisez l'état à chaque itération ; lorsqu'un problème survient à deux heures du matin, cette trace est votre seule preuve.

Règle 2 : reculez, ne tournez pas à vide

Pour une tâche qui prend une minute, une interrogation à intervalle fixe d'une seconde est du gaspillage ; et lors de l'exécution de tâches par lots, une interrogation agressive peut atteindre les limites de débit. Commencez à environ deux à trois secondes, multipliez par environ 1,5 à chaque tour, avec un plafond de dix à quinze secondes. Le nombre total de requêtes pour une tâche d'une minute passe de soixante à moins de quinze, tandis que la latence de détection dans le pire des cas reste égale à la valeur du plafond.

Règle 3 : séparez l'actif des métadonnées

La charge utile de la réponse finalisée contient les deux. La vidéo elle-même est livrée sous forme d'URL (et généralement avec une date d'expiration), tandis que tout le reste — ID de tâche, modèle, durée, état, temps écoulé — sont des métadonnées sur la façon dont vous l'avez obtenue. Lisez l'URL, téléchargez rapidement, et stockez-la vous-même. Les URL d'actifs générés ne sont pas un CDN permanent ; traitez-les comme une remise, pas comme un domicile. Persistez l'ID de tâche avec votre propre copie, pour pouvoir retracer n'importe quel clip jusqu'à la requête exacte qui l'a produit.

Note sur failed

L'état failed est un résultat au niveau de la tâche, pas une erreur de transport. L'appel HTTP a réussi ; la génération n'a pas réussi. Lisez la charge utile d'erreur — elle peut indiquer un refus pour politique de contenu, une combinaison de paramètres non prise en charge ou une défaillance interne. Réessayer tel quel un refus pour politique ne fera qu'échouer à nouveau, alors branchez d'abord selon la cause avant d'envisager une nouvelle tentative.

Gérer les erreurs, les délais d'expiration et les nouvelles tentatives

Distinguez deux mondes d'erreurs et traitez-les séparément.

Les erreurs au niveau du transport sont des échecs HTTP : réinitialisations de connexion, réponses 5xx, limites de débit 429 et délais d'expiration côté client. Elles ne disent pas si la tâche a été exécutée. Réessayez avec un recul exponentiel et un jitter, en limitant le nombre de tentatives.

Les erreurs au niveau de la tâche sont des états terminaux dans une réponse HTTP réussie. La tâche a été exécutée et a produit un résultat définitif. Réessayer l'interrogation ne sert à rien ; si vous voulez réessayer, c'est une nouvelle soumission, et seulement si la cause de l'échec est temporaire.

Réessayer la bonne chose

C'est la partie subtile. Si votre appel de soumission expire, vous ne savez pas si le serveur a accepté la tâche. Une nouvelle soumission aveugle peut produire deux générations et deux débits. Le schéma le plus sûr consiste à rendre la soumission idempotente à l'aide d'une clé de requête générée par le client, que vous envoyez en en-tête ou en champ du corps de requête, pour qu'une soumission en double renvoie la tâche d'origine au lieu d'en démarrer une nouvelle. Si la surface d'API que vous utilisez ne l'offre pas, alors en cas de délai d'expiration de la soumission, journalisez le hachage de l'invite et la durée, et vérifiez vos tâches récentes avant de soumettre à nouveau.

Des délais d'expiration à chaque niveau

Définissez trois délais d'expiration distincts, sans les confondre :

• Délai par requête — court, par exemple dix à quinze secondes. Il limite un seul appel HTTP, pas la tâche.
• Échéance globale de la tâche — le budget en temps réel pour l'ensemble de la génération. Si elle est dépassée, marquez la tâche comme orpheline, alertez, puis continuez.
• Délai côté client — si un utilisateur attend, décidez si vous diffusez la progression ou renvoyez un handle de tâche au frontend.

Stratégie de nouvelle tentative pratique

Réessayez 429 et 5xx avec recul, en fixant une limite basse. Ne réessayez jamais 400, 401, 403 ou 422 — ce sont des bugs dans votre requête, les répéter ne fera que consommer du quota. Journalisez le corps de réponse de chaque échec ; les charges utiles d'erreur HiAPI indiquent généralement le champ problématique.

Sécurité des lots

Lors d'une distribution de nombreuses tâches, ajoutez une limite de concurrence et des délais de démarrage avec jitter. Cent soumissions simultanées sont un accident de limite de débit qui s'annonce. Un pool de cinq à dix workers, chacun interrogeant indépendamment, est bien plus stable et plus facile à observer.

Liste de contrôle de production avant mise en ligne

Avant que cela ne quitte le portable, figez ces décisions.

• Délais d'expiration et échéances. Chaque appel a un délai par requête, il existe une échéance globale de tâche, et une politique claire sur ce qui se passe lorsqu'une tâche devient orpheline. Écrivez-les comme des constantes, pas comme des nombres magiques.
• Persistance des ID. Stockez le job_id et le hachage de l'invite avant le début de l'interrogation. C'est la clé qui rend possibles les redémarrages et l'audit.
• Stockage des actifs. En cas de succès, téléchargez la vidéo finalisée dans votre propre bucket de stockage. N'envoyez jamais une URL que vous ne contrôlez pas comme référence permanente dans le frontend ou la base de données.
• Journalisation. Journalisez chaque transition d'état, avec l'ID de tâche, le modèle, la durée, le préréglage et le temps écoulé. Lorsque des questions de coût ou de qualité apparaissent, c'est l'ensemble de données qui permet d'y répondre.
• Conscience des coûts. La facturation est calculée à la seconde de sortie, donc la durée est votre principal levier de coût. Le préréglage turbo maintient la latence (et donc l'occupation des workers) basse. Suivez les secondes générées par fonctionnalité, pour que les discussions de coût reposent sur des chiffres réels plutôt que sur des suppositions.
• Idempotence. Utilisez une clé de requête générée par le client à la soumission, et établissez des règles sur ce qui constitue une nouvelle soumission sûre.
• UX d'échec. Décidez dès maintenant ce que l'utilisateur voit en cas d'échec au niveau de la tâche : bouton de nouvelle tentative, invite de repli, ou simple message texte. Le silence total est le pire choix.
• Versionnement des invites. Placez les invites dans la configuration, pas en ligne dans les gestionnaires, pour pouvoir comparer les sorties de différentes variantes sans redéploiement.

Le point de terminaison lui-même est petit — une soumission, une interrogation. Presque tout l'effort d'ingénierie se situe dans le cycle de vie qui l'entoure, et c'est là que se décide la qualité de production. Commencez par la référence du modèle kling-2.5-turbo/text-to-video sur HiAPI, puis construisez autour de lui l'échafaudage décrit ici.