Guide de l’API Kling 4.0 : votre première vidéo avec Python et cURL

L’API Kling 4.0 sur PoYo utilise un seul identifiant de modèle, kling-4.0, pour le texte-vers-vidéo, la génération à partir d’une première et d’une dernière image, les références visuelles et le montage vidéo. Vous soumettez une requête, conservez son identifiant de tâche, puis interrogez son statut jusqu’à la fin de la tâche. Ce guide suit le schéma actuel de PoYo, vérifié le 24 octobre 2026 ; les noms de champs d’un autre fournisseur ne sont pas interchangeables.

Ouvrez le playground Kling 4.0 pour tester les entrées visuellement, ou consultez la documentation de l’API.

Générer une première vidéo avec cURL

Définissez POYO_API_KEY dans l’environnement de votre shell, puis soumettez cette requête de cinq secondes. Gardez la clé sur votre serveur plutôt que dans le code exécuté par le navigateur.

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Lisez data.task_id dans la réponse JSON : une soumission réussie n’est pas encore une vidéo terminée. Remplacez YOUR_TASK_ID ci-dessous par cette valeur :

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Les statuts documentés sont not_started, running, finished et failed. Une fois la tâche terminée, cherchez le file_url de la vidéo dans data.files. En cas d’échec, examinez error_message et conservez l’identifiant de tâche pour le diagnostic. Interroger une tâche existante ne nécessite pas de la soumettre à nouveau.

Une boucle d’interrogation Python bornée

Installez requests et exécutez ce code sur votre backend. Il vérifie à la fois les erreurs HTTP et les erreurs applicatives, s’arrête si la tâche échoue et limite l’attente à 30 minutes. Un dépassement de délai signifie qu’il faut revérifier la même tâche plus tard : renvoyer automatiquement la soumission pourrait créer une seconde tâche facturable.

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

Choisir le bon mode d’entrée

Le champ de vidéo source active le mode montage même si des images de référence sont également présentes. En image-vers-vidéo, la première image fixe l’image de départ ; une seconde image définit l’image de fin. Les images de référence guident l’identité ou le style et n’ont pas le même rôle que les images de début et de fin.

Les limites à valider avant la soumission

La génération accepte des durées entières de 3 à 30 secondes, en 720p ou 1080p. Dans ce schéma PoYo, un prompt standard est limité à 26 000 caractères. Chaque plan de multi_prompt accepte jusqu’à 512 caractères ; si la durée d’un plan est omise, elle vaut cinq secondes par défaut. La somme des durées des plans doit être comprise entre 3 et 30 secondes, et une durée explicite au niveau supérieur doit être égale à ce total.

Les références autorisent jusqu’à 10 images, cinq vidéos et sept sujets, dans une limite combinée de 15 ressources. Une première image compte à la fois dans la limite d’images et dans la limite globale. Chaque vidéo de référence ou de sujet doit durer entre 3 et 30 secondes ; leur durée réelle cumulée ne peut pas dépasser 30 secondes. N’arrondissez pas les durées à la baisse pour faire passer une entrée trop longue à la validation.

Comprendre votre première facture

Une requête de cinq secondes en 720p sans entrée vidéo coûte 142,5 crédits, soit 0,7125 $ au taux de conversion actuellement affiché. Une entrée vidéo modifie à la fois le tarif et la durée facturable. Consultez les exemples de tarification avant d’estimer un flux de travail avec vidéo de référence ou de montage.

Le produit officiel destiné aux créateurs met en avant des contrôles supplémentaires, dont plusieurs images clés. Le schéma de PoYo expose ici jusqu’à deux images de début et de fin et des prompts par plan ; n’envoyez pas à cet endpoint des champs inventés comme keyframes, seed, negative_prompt ou generate_audio. Pour des exemples fonctionnels, poursuivez avec le guide des prompts et le tutoriel Omni Reference.

Questions fréquentes

L’identifiant de modèle de l’API est-il kling-4-0 ? Non. C’est le slug de la page. L’identifiant de modèle à utiliser dans la requête est kling-4.0.

Puis-je demander de la 4K ici ? Cet endpoint PoYo n’accepte actuellement que 720p et 1080p. Vérifiez le schéma du fournisseur plutôt que de reprendre les spécifications marketing de l’application pour créateurs.

Puis-je utiliser un callback ? La requête de soumission accepte un callback_url au niveau supérieur. Consultez la documentation actuelle pour la gestion des callbacks ; l’exemple d’interrogation ci-dessus n’en dépend pas.

Par où commencer ? Lancez d’abord une courte requête texte seule, enregistrez son identifiant de tâche et son résultat, puis ajoutez une modalité d’entrée à la fois dans le playground.