Comment utiliser l'API kling-3.0-omni/transformation : retouche vidéo avec curl et Python

kling-3.0-omni/transformation est le modèle de vidéo-vers-vidéo de Kling 3.0 Omni : vous fournissez une vidéo source et un prompt textuel, et il réécrit l'apparence de cette vidéo — la scène, le style, le sujet — tout en conservant le mouvement et la temporalité d'origine. Sur hiapi, vous l'appelez via le même endpoint asynchrone unifié que tous les autres modèles de génération : POST /v1/tasks. Ce guide fournit un tableau des paramètres vérifié sur l'API réelle, des requêtes curl prêtes à copier-coller, un client Python complet (qui interroge et télécharge le résultat), ainsi que les patrons de production (callback, idempotence, gestion des erreurs) dont vous avez besoin avant de l'intégrer à une application réelle.

Chaque nom de champ, valeur d'énumération et structure de réponse ci-dessous a été vérifié contre l'API réelle.

Ce que vous allez construire + prérequis

Un petit programme : soumettre une tâche de retouche, attendre qu'elle se termine, puis télécharger le .mp4 retouché. Il vous faut deux choses :

1. Une clé API hiapi. Créez-en une dans la console hiapi — son format ressemble à sk-.... Chaque requête utilise Authorization: Bearer sk-<your-key>.
2. Une URL de vidéo source accessible publiquement. Le modèle télécharge votre vidéo côté serveur, il faut donc une URL http(s) publique (votre propre CDN, un espace R2/S3 avec un objet public, etc.), et non un chemin de fichier local. Une seule URL est autorisée.

Le modèle et ses paramètres

La structure externe de la requête est {"model": ..., "input": {...}}. Le schéma de input est strict — seuls les trois champs suivants sont acceptés ; tout champ superflu est rejeté avec un 400.

Champ	Type	Obligatoire	Description
prompt	string	Oui	Décrit le style/la scène/le sujet cible. L'intensité de la retouche se règle aussi ici — il n'existe aucun paramètre numérique strength/fidelity.
video_urls	array	Oui	Exactement une URL de vidéo source publique (minItems vaut 1, maxItems vaut 1).
resolution	string (énumération)	Oui	L'une des valeurs 720p, 1080p, 4k.

Quelques points qui piègent facilement :

• Aucun paramètre duration. La durée et le rapport d'aspect de la sortie suivent la vidéo source (3 à 15,5 secondes), et la facturation se fait sur la durée de la sortie finale.
• L'id du modèle contient lui-même -omni : kling-3.0-omni/transformation (certains autres endpoints Omni utilisent kling-3.0/...). Utilisez directement cet id comme valeur de model.
• L'intensité de la retouche est pilotée par le prompt. Pour une modification légère, écrivez « retouche légère, en conservant les traits du visage et l'éclairage » ; pour une modification importante, écrivez « réimaginer entièrement en cartoon 2D cel-shading ».

Exemple minimal fonctionnel (curl)

# 1) Créer une tâche de retouche
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/transformation",
    "input": {
      "prompt": "Retoucher cette scène dans un style d'animation aquarelle dessinée à la main, avec une texture de papier douce et une lumière chaude de crépuscule ; conserver le mouvement de caméra et le sujet d'origine.",
      "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
      "resolution": "720p"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2) Interroger la tâche jusqu'à l'état terminal
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01... \
  -H "Authorization: Bearer sk-<your-key>"
# data.status passe par : queued -> handling -> archiving -> success
# En cas de succès, data.output[0].url est le .mp4 retouché

L'id de tâche que vous interrogez provient de data.taskId dans la réponse de création — pas du id de premier niveau. Les chaînes de statut sont queued / handling / archiving / success (terminal) ou fail ; ne supposez pas succeeded/completed.

Client Python complet (création → interrogation → téléchargement)

import os
import time
import requests

API_KEY = os.environ["HIAPI_KEY"]            # votre clé sk-...
BASE = "https://api.hiapi.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_restyle(source_video_url: str, prompt: str, resolution: str = "720p") -> str:
    body = {
        "model": "kling-3.0-omni/transformation",
        "input": {
            "prompt": prompt,
            "video_urls": [source_video_url],   # exactement une URL publique
            "resolution": resolution,           # "720p" | "1080p" | "4k"
        },
    }
    r = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"Soumission refusée : {data}")
    return data["data"]["taskId"]


def wait_for_video(task_id: str, poll_s: int = 10, timeout_s: int = 900) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"Échec de la tâche : {data.get('error')}")
        time.sleep(poll_s)                      # queued / handling / archiving
    raise TimeoutError(f"{task_id} n'a pas terminé dans les {timeout_s} secondes")


if __name__ == "__main__":
    task_id = create_restyle(
        source_video_url="https://your-cdn.example.com/source-clip.mp4",
        prompt=(
            "Retoucher cette scène dans un style d'animation aquarelle dessinée à la main, "
            "texture de papier douce, lumière chaude de crépuscule ; conserver le mouvement "
            "de caméra et le sujet d'origine."
        ),
        resolution="720p",
    )
    print("Tâche :", task_id)

    url = wait_for_video(task_id)
    print("URL de la vidéo :", url)

    # Le fichier de sortie se trouve sur temp.hiapi.ai et expire (environ 7 jours). Téléchargez-le maintenant.
    clip = requests.get(url, timeout=120).content
    with open("restyled.mp4", "wb") as f:
        f.write(clip)
    print("restyled.mp4 enregistré,", len(clip), "octets")

Placez la clé dans une variable d'environnement puis exécutez :

export HIAPI_KEY=sk-<your-key>
python restyle.py

Patrons de production

Utiliser un callback plutôt qu'un interrogatoire fréquent

Pour tout usage au-delà d'un script, enregistrez un webhook afin de ne pas maintenir une boucle d'interrogation. callback est un champ de premier niveau — au même niveau que model et input, jamais à l'intérieur de input :

{
  "model": "kling-3.0-omni/transformation",
  "input": {
    "prompt": "Retoucher cette scène dans un style cartoon 2D cel-shading, contours épais ; conserver le mouvement d'origine.",
    "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
    "resolution": "1080p"
  },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

• callback.when n'accepte que final (valeur par défaut). Lorsque la tâche atteint un état terminal, il est mis en file une fois, et il se déclenche en cas de succès comme d'échec. La sémantique de livraison est au moins une fois, donc le même callback peut encore arriver plusieurs fois (voir ci-dessous).
• Le corps de la requête POST livré est identique à l'objet data obtenu via GET /v1/tasks/<id> — votre gestionnaire peut donc lire status, output[].url et error sans avoir à récupérer de nouveau.
• Placer callback dans input échouera à la soumission avec l'erreur additional properties 'callback' not allowed (le schéma input de chaque modèle est strict).

Idempotence et sémantique de livraison

Les callbacks sont au moins une fois et non exactement une fois — le même taskId peut arriver plusieurs fois. Utilisez taskId comme clé de votre gestionnaire et rendez l'étape « marquer comme terminé + stocker la vidéo » idempotente. hiapi réessaie les callbacks non-2xx/timeout selon le rythme immédiat → +1 minute → +5 minutes → +20 minutes, jusqu'à 4 tentatives ; votre endpoint doit renvoyer HTTP 2xx pour arrêter les tentatives.

Télécharger la sortie immédiatement

data.output[0].url pointe vers temp.hiapi.ai et inclut un expireAt (horodatage Unix, TTL d'environ 7 jours). Une fois expiré, l'objet est purgé et cette URL renvoie 404 — interroger de nouveau la tâche renvoie la même URL, mais ne régénère pas le fichier. Dès qu'une tâche réussit, copiez immédiatement les octets dans votre propre stockage.

Gestion des erreurs

Trois formes d'échec à traiter par branchements :

• Erreur de requête (HTTP 400) — structure plate, aucune tâche créée : {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: resolution: value must be one of '720p', '1080p', '4k'"}
• Échec d'authentification (HTTP 401) — structure imbriquée : {"error":{"code":"permission_denied","type":"hiapi_error", ...}}
• Échec de la tâche — la soumission renvoie 200 et un taskId, mais l'interrogation ultérieure montre data.status == "fail" avec data.error. Les tâches échouées ne sont pas facturées (le montant prélevé est remboursé lorsque la tâche échoue définitivement). Une URL source inaccessible ou non téléchargeable se manifeste ici.

Coûts

kling-3.0-omni/transformation est facturé à la seconde de sortie, avec un tarif qui varie selon la résolution demandée (720p à 0,143 $/s, 1080p à 0,193 $/s, 4k à 0,479 $/s, vérifié le 21 octobre 2026). Avant de traiter des vidéos en lot, consultez la page de tarification hiapi en direct pour obtenir le tarif actuel à la seconde — les coûts des tâches vidéo s'accumulent bien plus vite que ceux des tâches d'image.

Lectures associées

• Page du modèle et spécifications : kling-3.0-omni/transformation sur hiapi
• Référence de l'endpoint : Créer une tâche — API asynchrone unifiée
• Tutoriel de la même série sur le même endpoint : L'API image-vers-vidéo de Kling AI en Python

Questions fréquentes

Comment contrôler l'intensité de la retouche ? Via le prompt, pas via un paramètre. Il n'existe aucun champ strength, fidelity ou creativity. Pour une modification légère, écrivez « retouche légère, conserver le visage et l'éclairage » ; pour une modification importante, écrivez « réimaginer entièrement en