Tutoriel
Comment appeler kling-3.0-omni/transformation via l'API HiAPI : guide curl et Python
Une démonstration complète des requêtes utilisables pour la conversion de style vidéo sur HiAPI
Sur cette page
Fonctionnalités et cas d'usage du point de terminaison transformation
kling-3.0-omni/transformation est le point de terminaison de conversion de style vidéo sur HiAPI. Vous lui fournissez deux choses : une vidéo source et une instruction de style en langage naturel. Il renvoie une nouvelle vidéo dans laquelle le contenu de la vidéo source est préservé, mais présenté dans le style visuel demandé.
Voyez-le comme une étape de post-production cachée derrière un appel HTTP. Pas besoin d'entraîner de modèle, de maintenir un cluster GPU ou de gérer des fichiers de checkpoints. Vous décrivez l'effet visuel souhaité, pointez vers une vidéo, et le point de terminaison produit le rendu.
Scénarios adaptés à ce point de terminaison
- Appliquer un style à des séquences existantes. Vous avez déjà une prise de vue et souhaitez qu'elle apparaisse en animation, aquarelle, grain de film, pâte à modeler ou tout autre effet. Le contenu et le mouvement viennent de votre vidéo ; le point de terminaison modifie la texture de surface.
- Maintenir un style cohérent en lot. Comme le style est exprimé par une instruction, vous pouvez réutiliser le même prompt sur de nombreuses vidéos sources pour obtenir un ensemble cohérent stylistiquement.
- Prototyper le développement de style. Les équipes créatives peuvent itérer à moindre coût sur des directions stylistiques avant d'investir dans des pipelines de production plus lourds.
Scénarios non adaptés
- Vous devez générer une vidéo à partir de zéro (la génération texte-vers-vidéo est une autre tâche).
- Vous avez besoin d'édition, de montage ou de composition image par image précise. La transformation ne fait que remodeler le style, pas le montage.
- Votre matériel source est uniquement audio ou une image statique.
Le reste de ce guide détaille pas à pas la structure de la requête, un appel curl directement exécutable, la version Python correspondante, ainsi que les détails opérationnels autour des sorties 4K et des tâches de longue durée.
Analyse de la requête : vidéo source, instruction de style et options de sortie
Une requête de transformation n'est pas complexe. Avant d'écrire du code, décomposez-la en trois groupes de champs : la vidéo source, l'instruction et les paramètres de sortie.
Vidéo source
Le point de terminaison doit pouvoir accéder à votre entrée. En pratique, vous passez une URL que la plateforme peut récupérer, ou un identifiant renvoyé par l'étape de téléversement de fichiers HiAPI. La règle pratique : le fichier source doit être accessible depuis le serveur, pas depuis votre ordinateur portable. Un chemin localhost ou un fichier derrière votre VPN ne fonctionnera pas.
Gardez le format source conservateur — utilisez des conteneurs et codecs largement pris en charge. Si votre vidéo est produite par un pipeline exotique et échoue à la validation, réencodez-la d'abord en MP4 H.264 standard. Cette étape à elle seule résout une grande partie des erreurs d'entrée.
Instruction de style
C'est la description en langage naturel de l'effet visuel cible. C'est le champ le plus influent de la requête, et celui qui mérite le plus d'être peaufiné.
- Décrivez le traitement visuel, pas le contenu. Le contenu vient de la vidéo ; dire au modèle ce qui est déjà à l'écran ne fait que gaspiller le budget du prompt.
- Soyez précis sur le médium et la texture : « animation en pâte à modeler image par image avec traces de doigts visibles » transmet bien plus que « animation ».
- Précisez ce qui doit être préservé lorsque c'est important : « garder les visages reconnaissables, mouvement de caméra inchangé ».
- Restez dans un paragraphe ciblé. Les prompts longs et contradictoires ont tendance à se moyenner en résultats fades.
Options de sortie
Les paramètres de sortie contrôlent la résolution et d'autres détails de livraison. La décision principale est de demander du 4K ou une résolution standard. Une résolution plus élevée consomme plus de calcul et prend plus de temps, il faut donc la considérer comme une décision consciente plutôt qu'un choix par défaut. Le point de terminaison fonctionne généralement en mode asynchrone, donc votre requête renvoie généralement une référence de tâche que vous devez interroger ou attendre, plutôt que le fichier final directement.
Une fois votre entrée associée à ces trois groupes de champs, le corps JSON réel de la requête devient clair.
Une requête curl utilisable dès le départ
La façon la plus rapide de confirmer votre compréhension est un appel minimal. La forme ci-dessous envoie une URL de vidéo source et une instruction de style, et demande un résultat en résolution standard. Remplacez les valeurs de remplacement par les vôtres.
curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": "Convertir en animation aquarelle dessinée à la main, bords fondus doux, texture de papier visible, palette chaude et limitée. Préserver les visages et le mouvement de caméra.",
"resolution": "1080p"
}'
Rôle de chaque partie
- Le chemin d'URL spécifie le point de terminaison. Il doit être exact ; une faute de frappe ici renvoie une erreur de routage, pas une erreur de validation.
- L'en-tête
Authorizationporte votre clé HiAPI. Exportez-la comme variable d'environnement plutôt que de la coller dans l'historique du shell. video_urlest la vidéo source. Elle doit pouvoir être récupérée par le serveur.promptest l'instruction de style. C'est le champ que vous modifierez le plus.resolutionest le paramètre de sortie. Commencez bas en résolution pour itérer, puis augmentez une fois l'effet fixé.
Interpréter la réponse
Une réponse réussie vous donne un objet de tâche. Notez l'identifiant de tâche et tout champ de statut :
{
"id": "job_abc123",
"status": "queued"
}
Les noms exacts des champs doivent être lus dans la réponse réelle, pas supposés. La bonne habitude est la même dans tous les langages : analysez le JSON, extrayez l'identifiant de tâche et considérez la vidéo terminée comme quelque chose qui arrive plus tard. N'écrivez pas de code qui suppose que la première réponse contient un fichier lisible.
La même requête en Python
La version Python est l'appel curl, avec le corps JSON exprimé sous forme de dictionnaire. Utiliser requests garde le code lisible et les dépendances légères.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": (
"Convertir en animation aquarelle dessinée à la main, bords fondus doux, "
"texture de papier visible, palette chaude et limitée. Préserver les visages et le mouvement de caméra."
),
"resolution": "1080p",
}
resp = requests.post(
f"{BASE}/kling-3.0-omni/transformation",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))
Interroger jusqu'à la fin de la tâche
Comme le rendu est asynchrone, enveloppez l'attente dans une boucle avec un nombre d'essais limité et un sommeil entre les vérifications. Le sommeil doit être suffisamment large pour ne pas marteler l'API, et un plafond total d'attente doit être défini pour qu'une tâche bloquée ne suspende pas votre processus de travail.
def wait_for_job(job_id, max_attempts=60, interval=10):
for _ in range(max_attempts):
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status == "failed":
raise RuntimeError(data.get("error") or "job failed")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish in time")
result = wait_for_job(job_id)
print(result.get("output") or result)
Le rendre sûr en production
- Lisez le chemin du point de terminaison et la route d'interrogation dans la documentation des réponses API, au lieu de coder en dur des suppositions susceptibles de dériver.
- Journalisez l'identifiant de tâche lors de la soumission. En cas de problème en aval, c'est votre seul point d'ancrage.
- Traitez
failedet les timeouts comme des résultats distincts. Une tâche échouée est généralement un problème de paramètre ; un timeout est généralement un problème de capacité ou de durée.
Gérer les sorties 4K et les tâches de longue durée
Deux variables dominent le comportement opérationnel de ce point de terminaison : la résolution de sortie et la durée d'entrée. Planifiez explicitement les deux.
Sortie 4K
Le 4K est une décision de livraison, pas une valeur par défaut. Chaque pixel de sortie consomme du calcul, et le saut relatif entre résolution standard et 4K est important. Un flux de travail raisonnable :
- Itérez sur l'instruction de style en basse résolution. La qualité du prompt est indépendante de la résolution, donc réglez d'abord l'effet à moindre coût.
- Verrouillez le prompt et la vidéo source.
- Relancez une fois en 4K pour la livraison.
Évitez de générer des variantes 4K dans une boucle serrée pendant que vous ajustez la formulation — c'est la façon la plus courante de gaspiller du budget sur des rendus que vous finirez par jeter.
Tâches de longue durée
Les vidéos sources plus longues prennent plus de temps à transformer, et le point de terminaison renvoie une référence de tâche plutôt qu'un fichier fini. Construisez votre client autour de cette réalité :
- Ne bloquez jamais une requête web sur le rendu. Soumettez, stockez l'identifiant de tâche, puis rendez immédiatement la main à l'appelant.
- Séparez la soumission de la récupération. Un processus de travail avec file d'attente et interrogation est plus robuste qu'une attente en ligne et survit aux redémarrages de processus.
- Persistez l'état des tâches. Si un processus de travail meurt en cours d'interrogation, la tâche ne disparaît pas ; vous pouvez reprendre depuis l'identifiant stocké.
- Si votre compte prend en charge les webhooks, utilisez-les, et conservez l'interrogation comme chemin de secours.
- Définissez un budget d'attente total qui reflète la durée maximale de vidéo attendue, pas un nombre arbitraire.
Un mode pratique
Découpez les vidéos sources plus longues que la durée typique en segments, transformez-les un par un, puis assemblez les résultats. Cela réduit le temps d'attente par appel, vous permet de réessayer un segment plutôt que le rendu entier, et rend les échecs peu coûteux. Assurez-vous que les frontières de segment ne coupent pas un mouvement rapide, sinon les jointures seront visibles.
Dépannage des pannes courantes
La plupart des pannes se classent en trois catégories : la vidéo source est illisible, les paramètres sont rejetés, ou la tâche ne se termine jamais. Isolez la catégorie avant de changer quoi que ce soit.
Erreurs de téléversement et d'accès à la source
Symptôme : la soumission échoue, ou la tâche échoue presque immédiatement pour une erreur d'entrée.
- L'URL n'est pas accessible publiquement. Testez-la depuis une machine en dehors de votre réseau. Une URL signée expirant entre la soumission et la récupération est le coupable typique.
- Format non pris en charge. Réencodez en MP4 H.264 standard et réessayez.
- Fichier tronqué ou corrompu. Téléchargez-le vous-même et lisez-le de bout en bout.
- Requête trop volumineuse. Si vous envoyez les octets du fichier en ligne plutôt qu'une URL, utilisez le flux de téléversement et passez l'identifiant renvoyé.
Erreurs de paramètres
Symptôme : une réponse 4xx à la soumission.
- JSON malformé. Vérifiez le corps avec un outil de lint. Les virgules finales et les guillemets non échappés sont des erreurs courantes dans les appels curl écrits à la main.
- Nom de champ ou type incorrect. Vérifiez contre le schéma de requête actuel ; passer la résolution en nombre alors qu'une chaîne est attendue échouera.
- Prompt vide ou contradictoire. Si l'instruction ne décrit rien, ou demande des styles mutuellement exclusifs, attendez-vous à une sortie faible ou à un rejet. Réécrivez autour d'une direction visuelle claire.
- Clé API manquante ou invalide. Vérifiez la valeur de l'en-tête et si la clé est valide pour ce point de terminaison.
Timeouts et tâches bloquées
Symptôme : la tâche reste en file d'attente ou en cours après votre budget d'attente, ou votre client abandonne.
- Distinguez les timeouts client des échecs de tâche. Un court timeout HTTP à la soumission ne signifie pas que la tâche n'a pas commencé ; vérifiez s'il existe un identifiant de tâche avant de resoumettre, sinon vous risquez de dupliquer des rendus.
- Les entrées longues et les sorties 4K prolongent le temps d'exécution. Si vous atteignez systématiquement le timeout, réduisez la résolution ou raccourcissez la vidéo pour confirmer que le flux fonctionne, puis remontez progressivement.
- Si la tâche rapporte
failed, lisez le message d'erreur avant de réessayer. Réessayer aveuglément une erreur de paramètre déterministe ne fait que multiplier les coûts.
Ordre de débogage efficace
Commencez par la requête la plus petite possible : une vidéo courte en résolution standard et une phrase de prompt. En cas de succès, réintroduisez un par un le vrai prompt, la vraie durée, puis le 4K, en ne changeant qu'une variable à la fois. L'étape qui casse vous indique la variable responsable.
Compromis entre coût et latence à planifier
Une fois la requête fonctionnelle, les décisions restantes sont opérationnelles. Trois leviers influencent simultanément le coût et la latence, et interagissent entre eux.
Résolution
La résolution de sortie est le levier le plus important. La facturation est liée au travail de rendu effectué, et une résolution de sortie plus élevée implique plus de travail. Règle empirique : itérer en basse résolution, livrer en haute résolution. Ne faites jamais tourner des expériences de style en 4K.
Durée d'entrée
Une vidéo source plus longue signifie plus de frames à transformer, donc plus de calcul et plus de temps réel. Si votre cas d'usage le permet, transformez un court extrait plutôt qu'un montage complet, ou découpez les longs matériels et ne transformez que les parties nécessaires.
Nouvelles tentatives
Sauf si l'échec survient avant le début de la tâche, chaque nouvelle tentative est un rendu complet. C'est pourquoi l'ordre de débogage compte : validez les paramètres à moindre coût avant de payer le rendu. Prévenez les soumissions en double en journalisant les identifiants de tâche et en vérifiant avant de resoumettre après un timeout client.
Traitement par lots et parallélisme
Les tâches parallèles réduisent le temps réel mais pas le coût total — et peuvent atteindre les limites de concurrence. Pour le travail par lots, une file modérée en parallélisme contrôlé est généralement préférable à un fan-out. Elle vous maintient sous les limites de débit, rend les échecs faciles à réessayer individuellement, et vous donne une courbe de dépense prévisible.
Checklist budgétaire
- Finalisez le prompt en basse résolution avant tout rendu de livraison.
- Mettez en cache les sorties terminées ; ne rendez pas à nouveau les mêmes entrées.
- Définissez des prévisions de dépense par tâche et par lot, et alertez lorsque le lot les dépasse.
- Suivez la durée des tâches en fonction de la résolution et de la durée d'entrée, afin de prévoir de nouveaux travaux à partir des exécutions passées.
- Considérez le 4K comme la dernière étape du flux, pas comme un mode interactif.
La tarification de ce point de terminaison est publiée sur le site HiAPI, alors consultez les tarifs actuels avant de planifier la taille de vos lots. Faites d'abord passer la requête minimale, puis augmentez délibérément la résolution et la durée — cet ordre garde votre latence et votre facture prévisibles.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage