Tutoriel
Comment utiliser topaz-upscale/video via l'API HiAPI : exemples curl et Python
Sur cette page
Ce que fait topaz-upscale/video et quand l'utiliser
topaz-upscale/video est le point de terminaison d'amélioration vidéo sur HiAPI. Vous lui envoyez une vidéo source et des instructions, et il renvoie une vidéo améliorée : résolution plus élevée, détails fins reconstruits et, en option, mouvement plus fluide grâce à l'interpolation de frames. Utilisez ce point de terminaison lorsque le matériel existe déjà et que le problème tient à la qualité, non à la génération de contenu.
Cas d'usage
Tâches typiques qui correspondent naturellement à ce point de terminaison :
- Archives et matériel ancien — enregistrements anciens, captures d'écran compressées ou médias hérités qui doivent paraître présentables à une résolution moderne.
- Pipelines de rendu — séquences terminées d'abord rendues en basse résolution pour la vitesse, puis améliorées pour la livraison.
- Nettoyage du mouvement — sources à faible fréquence d'images nécessitant des frames interpolées pour éviter les saccades à la lecture.
- Variantes de livraison — un master, plusieurs niveaux de sortie, avec amélioration appliquée par niveau.
Quand le choisir plutôt qu'une alternative
La décision se résume généralement à trois questions :
- Le problème tient-il à la résolution et aux détails, ou au contenu ? Si vous devez inventer de nouveaux pixels (une scène qui n'a jamais été filmée), ce n'est pas le bon outil. L'amélioration suppose des frames sources réelles sous-jacentes.
- Votre pipeline tolère-t-il un travail asynchrone ? Les tâches vidéo ne sont pas instantanées. Si votre expérience utilisateur exige une réponse en moins d'une seconde, ce point de terminaison doit s'exécuter dans une tâche d'arrière-plan, et non dans le gestionnaire de requête.
- Avez-vous besoin à la fois d'interpolation de frames et d'agrandissement ? Si la fluidité du mouvement compte, vous voulez les deux capacités en un seul passage plutôt que de chaîner plusieurs outils distincts.
topaz-upscale/videocouvre les deux.
Si votre source est une image fixe unique, utilisez plutôt l'upscaler d'image. Si la source est correcte mais mal encodée, corrigez d'abord l'encodage — l'amélioration ne peut pas récupérer des détails déjà détruits par une compression agressive, et vous paierez du calcul sans gain de qualité.
Préparer la requête avant le premier appel
La plupart des échecs au premier appel viennent de pièces manquantes, pas de mauvais prompts. Préparez ces éléments avant d'écrire la moindre ligne de code.
Compte et identifiants
Vous avez besoin d'une clé API HiAPI autorisée à accéder à topaz-upscale/video. Conservez la clé dans une variable d'environnement plutôt que dans le code source — chacun des exemples ci-dessous lit HIAPI_API_KEY depuis l'environnement.
export HIAPI_API_KEY="your-key-here"
Média source accessible
Le modèle doit pouvoir récupérer votre entrée. Deux modes fiables :
- URL publique ou signée — une URL que le service peut télécharger sans authentification interactive. Si votre stockage exige des liens signés, générez un lien avec une validité confortable et pensez à le régénérer lors des nouvelles tentatives, sinon une tâche longue échouera en cours de route.
- Téléverser d'abord — poussez le fichier via le mécanisme de téléversement de la plateforme et référencez l'identifiant renvoyé. C'est le choix le plus sûr pour les gros fichiers et tout ce qui se trouve derrière un réseau privé.
Caractéristiques de la source à vérifier
Avant de dépenser un appel, vérifiez :
- Durée. Une longue vidéo signifie une longue tâche. Si vous testez, extrayez un extrait de 5 à 10 secondes au milieu de la source — le milieu est généralement plus représentatif que les premières frames.
- Codec et conteneur. Les codecs rares peuvent parfois échouer au décodage. En cas de doute, remuxez dans un conteneur courant.
- Fréquence d'images. Notez-la précisément ; elle servira au raisonnement sur l'interpolation de frames.
- Résolution. Notez les dimensions exactes de la source, pour que votre comparaison avant/après soit honnête.
Définir clairement votre objectif de sortie
Décidez de la résolution et de la fréquence d'images de sortie avant le premier appel, pas après. Des réglages d'amélioration raisonnables pour passer d'une source 720p à 1080p diffèrent de ceux pour passer d'une source 480p à 4K. Notez la cible ; vous la réutiliserez dans chaque requête suivante.
Lancer un appel avec curl
La requête est un POST vers le point de terminaison topaz-upscale/video avec un corps JSON. Voici un exemple complet et exécutable — remplacez l'URL du média par la vôtre.
curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "topaz-upscale/video",
"input": {
"video": "https://your-bucket.example.com/clips/source_720p.mp4"
},
"parameters": {
"target_resolution": "1080p",
"target_fps": 60,
"interpolation": "smooth",
"detail": "balanced"
},
"prompt": "Restaurer les textures fines des tissus et de la peau, conserver un grain naturel, interpoler à 60 fps sans ghosting"
}'
Interpréter la réponse
La réponse immédiate confirme la tâche. Vous recevez un identifiant de tâche et un champ de statut. Le travail vidéo est asynchrone, donc le schéma réel est :
# 1. Soumettre et récupérer l'id de la tâche
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | jq -r '.id')
# 2. Interroger jusqu'à un statut terminal
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'
Trois champs importent lors de la lecture du résultat :
status— passe de la file d'attente à l'exécution puis à un état terminal. Traitez tout statut non reconnu comme « continuez d'attendre » plutôt que comme un succès.output— présent en cas de succès, contient l'URL ou l'identifiant de la vidéo améliorée.error— présent en cas d'échec. Lisez le message littéralement ; il indique généralement le champ problématique.
Si vous itérez sur les prompts, placez le corps de la requête dans un fichier (request.json) et utilisez -d @request.json. Cela garde l'historique du shell propre et vous permet de comparer différentes versions d'une même requête.
Appeler le même point de terminaison depuis Python
La version Python est une fine enveloppe autour du même contrat HTTP. Utilisez requests, gardez la clé dans l'environnement et encapsulez la soumission et la boucle d'interrogation dans une fonction, afin que l'appelant n'ait pas à savoir que c'est asynchrone.
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",
}
def enhance_video(
video_url: str,
prompt: str,
target_resolution: str = "1080p",
target_fps: int = 60,
poll_interval: float = 5.0,
timeout: float = 1800.0,
) -> str:
payload = {
"model": "topaz-upscale/video",
"input": {"video": video_url},
"parameters": {
"target_resolution": target_resolution,
"target_fps": target_fps,
"interpolation": "smooth",
"detail": "balanced",
},
"prompt": prompt,
}
resp = requests.post(f"{BASE}/video/enhance",
headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
job_id = resp.json()["id"]
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
if data["status"] == "succeeded":
return data["output"]["video"]
if data["status"] == "failed":
raise RuntimeError(data.get("error", "Échec de l'amélioration"))
time.sleep(poll_interval)
raise TimeoutError(f"La tâche {job_id} ne s'est pas terminée dans le délai imparti")
Points d'attention pour l'utiliser dans un vrai pipeline
- Interrogation avec backoff exponentiel. Un intervalle fixe de cinq secondes convient à un script shell ; en production, recourez au backoff avec un plafond d'intervalle. Les longues vidéos peuvent prendre du temps ; interroger plus souvent ne les fera pas terminer plus vite.
- Idempotence. Si l'appel de soumission expire, vous ne savez peut-être pas si la tâche a démarré. Enregistrez le corps de la requête avec l'id de tâche afin de repérer les doublons au lieu de resoumettre aveuglément.
- Persistez l'id de tâche. Écrivez-le en base dès réception. Si le processus meurt en cours d'interrogation, vous pourrez reprendre par id sans payer une seconde amélioration.
Recettes de prompts pour l'interpolation de frames
L'interpolation de frames est l'endroit où les prompts dérapent le plus facilement — soit trop vagues pour guider quoi que ce soit, soit trop prescriptifs, poussant le modèle vers des objectifs contradictoires. Le prompt coexiste avec les paramètres structurés ; laissez la formulation porter sur l'intention et la nature du mouvement, et laissez les paramètres porter les cibles numériques.
Modèle : décrire le mouvement, pas les mathématiques
Mauvais :
interpolate
Meilleur :
Interpoler vers une fluidité à 60 fps. Conserver le rythme de mouvement d'origine — ne pas modifier la vitesse. Les panoramiques et mouvements de caméra doivent être linéaires et stables ; éviter les distorsions sur les bords des frames.
Vous avez déjà indiqué la fréquence d'images cible dans parameters. Le prompt doit décrire à quoi ressemble un mouvement fluide pour ce matériel.
Modèle : nommer les artefacts à éviter
Lisser du 24p vers du 60 fps. Éviter le ghosting sur les mains en mouvement rapide, éviter les traînées autour des objets fins comme les barreaux et les cheveux. Le fond statique doit rester parfaitement immobile.
Nommer les modes de défaillance spécifiques est bien plus efficace que « haute qualité ». Le modèle peut vérifier sa propre sortie par rapport à des instructions concrètes.
Modèle : séparer mouvement et texture
Pour cette passe, se concentrer uniquement sur la fluidité du mouvement. Conserver les détails et le grain existants — la restauration de texture est traitée séparément.
Utile lorsque vous chaînez deux étapes de traitement, afin que chaque prompt n'ait qu'une seule responsabilité.
Modèle : traiter des séquences à mouvement mixte
Pour une séquence d'interview avec caméra fixe mais sujet en mouvement, indiquer explicitement que la caméra est immobile fonctionne bien :
Interpoler vers 60 fps. La caméra est fixe — l'arrière-plan doit être totalement immobile, sans scintillement. Seule la tête et les mains de la personne qui parle doivent montrer un mouvement fluide.
Résistez à l'envie d'écrire de longues dissertations. Trois phrases couvrant le mouvement cible, les artefacts à éviter et ce qui doit rester immobile couvrent presque tous les cas.
Recettes de prompts pour la reconstruction des détails
La reconstruction des détails est la moitié de la tâche qui invente une structure fine plausible. Le mode de défaillance est la texture hallucinée : la peau devient plastique, la végétation devient du bruit, le texte devient illisible. Le prompt doit plafonner l'invention.
Modèle : s'ancrer à la source
Reconstruire les détails de manière cohérente avec les frames source. Ne pas inventer de textures que les pixels d'origine ne suggèrent pas. Là où les détails sont réellement perdus, préférer un résultat doux et crédible à du bruit sur-accentué.
Cette seule instruction prévient la plupart des pathologies de sur-accentuation.
Modèle : nommer les matériaux à l'écran
Restaurer les détails fins des textures de tissu, des mèches de cheveux et des pores de la peau. Conserver des teints naturels et des pores irréguliers — éviter l'aspect lissé et retouché. Les surfaces métalliques doivent conserver leurs reflets existants, sans en créer de nouveaux.
Les instructions spécifiques aux matériaux donnent au modèle des contraintes exploitables, sans long paragraphe générique.
Modèle : protéger le texte et les graphiques
Ce clip contient des sous-titres incrustés et des logos. Le texte doit rester net et lisible, sans distorsion. Ne pas redessiner ni modifier le style d'aucun élément graphique.
Le texte est le détail le plus risqué — un sous-titre illisible est pire qu'un sous-titre légèrement flou. Si la lisibilité est critique, vérifiez-la à l'étape de comparaison plutôt que de faire confiance au prompt.
Modèle : moduler l'accentuation de façon intentionnelle
Appliquer une quantité modérée de restauration des détails. Viser un rendu naturel à 1080p, et non une image fixe sur-accentuée. Une légère douceur est acceptable ; le ringing et les halos ne le sont pas.
Combiner les deux
Lorsque vous interpolez et reconstruisez en un seul passage, écrivez un prompt qui couvre les deux, mais avec une seule préoccupation par proposition :
Reconstruire les textures fines — tissu, cheveux, peau — en cohérence avec la source, en évitant le lissage plastique. Interpoler vers 60 fps, avec un mouvement stable, sans ghosting sur les mains, et un arrière-plan parfaitement immobile.
Comparer la sortie avant/après
Une vidéo améliorée qui semble magnifique sur une seule frame peut s'effondrer en mouvement. Mettez en place une procédure de comparaison fixe et exécutez-la à chaque changement de paramètre ou de prompt ; sinon, vous devinez, et vos suppositions coûtent cher.
Construire un jeu de clips de test standard
Choisissez trois clips courts (5 à 10 secondes chacun), à ne jamais modifier :
- Simple — source bien éclairée, mouvement lent, propre. Doit paraître quasi parfaite ; sinon, quelque chose est mal configuré.
- Difficile — mouvement rapide, détails fins ou types de mouvement mixtes. Les artefacts d'interpolation y apparaîtront.
- Adversarial — texte à l'écran, structures fines ou compression antérieure agressive. Les hallucinations y apparaîtront.
Exécutez chaque modification de prompt ou de paramètre sur les trois. Un changement qui aide sur le clip simple mais dégrade le clip adversarial n'est pas une amélioration.
Comparer dans cet ordre
- Comparaison côte à côte à 100 % de zoom. N'utilisez pas l'ajustement à la fenêtre, les artefacts s'y cachent. Vérifiez les mêmes zones recadrées : visages, zones de texte et zones à fort mouvement.
- Navigation image par image. Avancez frame par frame dans les portions à mouvement rapide, à la recherche de ghosting, de distorsions et de scintillements.
- Lecture à vitesse réelle. Beaucoup d'artefacts disparaissent en navigation image par image mais apparaissent en mouvement, et inversement. Regardez les deux.
- Vérification de la lisibilité du texte. Relisez chaque sous-titre de la version améliorée par rapport à la source. C'est le test objectif réussite/échec le plus rapide dont vous disposez.
Qualité et coût à parts égales
La facturation suit le travail effectué par le point de terminaison — la durée et la résolution de sortie sont les facteurs déterminants ; consultez le panneau de tarification du site pour les tarifs actuels. Conséquence pratique : les longs clips apportent des gains de qualité marginaux et représentent souvent un moins bon rapport qualité-prix que les clips courts apportant une amélioration nette. Pour chaque configuration candidate, notez la durée et la résolution de sortie produites, et demandez-vous si l'amélioration visible justifie la dépense. Gardez les vainqueurs, abandonnez le reste, et avant de brancher le point de terminaison dans un pipeline automatisé, figez une configuration et documentez-la — prompt, paramètres et résultats de test — afin que les changements futurs puissent être mesurés par rapport à elle.
Résoudre les problèmes de requête courants
La plupart des frictions d'intégration avec topaz-upscale/video se rangent dans quelques catégories. Traitez-les dans cet ordre.
Authentification et accès
401 signifie que la clé est absente, mal formée ou non envoyée — vérifiez que la variable d'environnement est bien définie dans le shell qui exécute la commande, et pas seulement dans votre éditeur. 403 signifie généralement que la clé est valide mais que le compte n'a pas accès à ce modèle. Vérifiez que le nom du modèle est exactement topaz-upscale/video.
Le service ne peut pas récupérer votre vidéo
C'est l'échec le plus fréquent. Symptôme : la tâche échoue tôt avec une erreur de téléchargement ou d'entrée. Causes :
- L'URL est privée ou nécessite une connexion interactive.
- L'URL signée expire avant que la tâche n'atteigne l'étape de téléchargement — particulièrement probable dans une longue file d'attente.
- L'hôte bloque les requêtes automatisées ou est trop lent et provoque un timeout.
Correctif : téléversez le fichier via la plateforme et référencez l'identifiant renvoyé, ou générez une URL signée avec une validité confortable au moment de la soumission.
Échec de décodage
Si l'erreur mentionne le média plutôt que la requête, remuxez la source dans un conteneur courant et réessayez. Testez d'abord le fichier localement — si votre propre lecteur peine, le service aussi.
La tâche tourne indéfiniment ou expire
Une longue source prend longtemps, et certaines requêtes prennent un temps disproportionné. Avant de resoumettre, vérifiez l'état de la tâche par id — vous voyez peut-être une tâche en file d'attente, pas une tâche en échec. Une resoumission aveugle peut doubler la dépense. Si vous interrogez depuis un script, assurez-vous que le timeout de votre client est supérieur à la durée attendue de la tâche, sinon vous abandonnerez une tâche qui tourne encore normalement.
La sortie semble pire que la source
La requête réussit mais le résultat est sur-accentué, plastique ou ghosté. C'est un problème de prompt, pas d'API : revenez aux recettes de reconstruction des détails et d'interpolation, ajoutez des plafonds explicites — « cohérent avec la source », « sans ghosting », « l'arrière-plan doit rester immobile ». Puis relancez votre jeu de comparaison standard.
Échecs intermittents et non reproductibles
Journalisez le corps complet de la requête en même temps que l'id de tâche à chaque appel. Sans les deux, vous ne pouvez pas savoir si l'échec vient d'une charge utile différente ou d'un problème temporaire du service. Avec une douzaine d'échecs documentés, un schéma apparaît généralement en quelques minutes.
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