API d'agrandissement vidéo : un flux de livraison et de contrôle qualité

Vous avez un court clip qui vous plaît, généré économiquement en 480p ou coupé dans des archives plus anciennes, et il doit sortir en 1080p ou 4K avec sa piste sonore intacte. Une API d'agrandissement vidéo fait cela en un seul appel, mais l'appel n'est que le milieu du travail. Ce qui décide si le fichier est exploitable, c'est ce que vous faites avant (terminer le montage, vérifier la source) et après (télécharger à temps, confirmer taille, durée et audio, exporter la toile exacte que la destination demande).

La version courte : agrandissez le montage final, une seule fois, au palier dont la destination a besoin. SpicyAPI Video Upscaler prend un MP4 de 3 à 60 secondes et un palier, et renvoie le même clip avec une résolution supérieure, en conservant la durée, le rapport d'aspect, le mouvement et la piste audio. Il n'y a pas de prompt. Prix : $0.006 par seconde source en 720p ou 1080p, $0.012 en 2K, $0.024 en 4K.

Ce que vous envoyez et ce que vous payez

Envoyez video_url (un lien direct vers un MP4, ou un fichier téléversé) et, en option, resolution : 720p, 1080p (par défaut), 2k ou 4k. Les MP4 téléversés peuvent aller jusqu'à 90 Mo. La facturation se fait par seconde du clip source, arrondie à la seconde entière, avec un minimum de trois secondes.

L'arrondi s'applique à chaque clip soumis, donc trois clips de 5.2 secondes sont facturés 18 secondes, et non 16. L'estimation affichée avant l'envoi suppose un clip de 60 secondes ($0.36 en 1080p, $1.44 en 4K) ; la partie inutilisée est libérée lorsque la tâche est réglée, si bien qu'un clip de 6 secondes est facturé 6 secondes. Une tâche en échec est remboursée.

L'argument de coût de l'agrandissement se trouve du côté de la génération. Un clip de 10 secondes généré en 480p avec Seedance 2.5 Spicy coûte $2.16 par tentative ; en 1080p natif, il coûte $10.80. Faites le brouillon en 480p, gardez la prise que vous voulez, et ajoutez $0.06 pour l'agrandir en 1080p. L'agrandisseur agrandit ce qui est déjà dans le cadre, donc un détail absent du brouillon n'apparaîtra pas. Si une petite étiquette ou un visage doit être juste, vérifiez-le dans le brouillon ou faites le brouillon à une résolution supérieure.

Préparez la source

Terminez d'abord le montage. Coupez, réordonnez et mixez l'audio avant d'agrandir. Sinon, chaque retouche ultérieure devrait être refaite sur un fichier ayant plusieurs fois plus de pixels, et vous payez pour traiter des secondes que vous jetterez. L'agrandisseur ne peut pas corriger une mauvaise prise : une main déformée ou un logo qui dérive revient plus grand.

Vérifiez le fichier. ffprobe montre ce que vous soumettez réellement, y compris une durée qui s'affiche arrondie à « 60 secondes » mais vaut 60.4 :

ffprobe -v error \
  -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels \
  -of json approved-source.mp4

Trois points à vérifier. La durée doit se situer entre 3 et 60 secondes. Un clip de téléphone peut se lire en portrait alors que l'image stockée est en paysage plus un indicateur de rotation (ffprobe -show_streams le liste dans side data) ; intégrez la rotation avant le téléversement. Et notez le flux audio : vous le comparerez au résultat.

Passez les clips déjà assez grands. Un clip au niveau demandé ou au-dessus revient à peu près à la même taille et est quand même facturé : un clip de 786x1178 envoyé en 720p est revenu en 784x1176. Si la source respecte déjà la spécification de la destination, exportez-la et arrêtez là.

Partez du master le plus propre. Les blocs de compression et le bruit sont agrandis avec tout le reste. Utilisez le master de génération ou de montage, pas une copie retéléchargée depuis un flux social.

Choisissez le palier selon la destination

Le palier est un budget de pixels avec le rapport d'aspect conservé, donc les sources atypiques reviennent avec des tailles atypiques. Un clip de 832x480 est revenu en 1896x1094 en 1080p et en 3792x2188 en 4K ; un clip de 854x480 est revenu en 1922x1080. N'attendez pas exactement 1920x1080.

• 720p ou 1080p pour les flux, les pages d'atterrissage et les publicités. Les deux coûtent pareil, alors choisissez selon la destination, pas selon le prix. 1080p est le palier par défaut et généralement le bon.
• 2K ou 4K pour les grands écrans, les présentations, ou si vous voulez recadrer ensuite. Ils coûtent deux et quatre fois plus et prennent plus de temps : environ 35 secondes pour une tâche de 5 secondes en 1080p et environ 100 secondes en 4K. Un fichier de 5 secondes en 4K fait environ 19 Mo.
• Si la destination exige une toile exacte, par exemple 1080x1920 pour un flux vertical, traitez cela comme une étape d'export séparée après l'agrandissement.

Agrandir un clip paysage puis le recadrer en vertical paie des pixels que vous jetez. Décidez du cadrage avant l'agrandissement et envoyez la composition finale.

Essayez d'abord dans le Playground

1. Ouvrez la page Video Upscaler et restez dans l'onglet Playground, en vue Form. Connectez-vous avec un compte crédité pour lancer l'exécution.
2. Sous Input video, déposez le MP4 validé (jusqu'à 90 Mo) ou collez un lien direct vers le fichier avec Asset URL. Une page qui lit la vidéo renvoie du HTML et l'appel échoue avec le débit remboursé ; téléverser le fichier est la voie la plus fiable.
3. Réglez Resolution sur 720p, 1080p, 2K ou 4K. Le champ est signalé comme influençant le prix, et l'estimation se met à jour avec votre choix.
4. Lancez, lisez le résultat en le comparant à la source (voir les vérifications ci-dessous), et ne le copiez qu'ensuite dans votre propre stockage.

Un clip de 5 secondes coûte quelques centimes même en 4K : essayez donc votre vrai clip au palier que vous comptez livrer avant d'écrire du code.

Exécutez-le ensuite depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY dans l'environnement de votre serveur et exécutez :

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/video-upscaler-v1/upscale",
    input_data={
        "video_url": "https://example.com/approved-product-ad.mp4",
        "resolution": "1080p",
    },
    idempotency_key=str(uuid.uuid4()),  # one key per approved clip and tier
)

print("Resume task:", task["taskId"], flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy the file to your own storage now

La création, l'attente, les reprises, les codes d'erreur et les téléchargements sont couverts dans le guide des tâches et la référence du SDK Python ; un fichier local passe par le flux de téléversement gratuit et est transmis comme URI spicy://. Le lien du résultat est de courte durée et le fichier est conservé environ 14 jours : consultez donc rétention et livraison avant de construire dessus. Une tâche au statut succeeded signifie seulement que le service a terminé ; marquez le clip comme livré une fois les vérifications ci-dessous réussies.

Ou laissez un agent l'exécuter

Quand un assistant doit lancer l'agrandissement, les trois outils officiels affichent le prix et vous demandent avant un appel payant.

• CLI. Mettez {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} dans input.json, puis :

``bash spicyapi tasks create --model spicyapi/video-upscaler-v1/upscale --input-file input.json --wait ``

Voir la documentation de la CLI ; npx @spicyapi/cli fonctionne sans installation.

• Serveur MCP. Ajoutez le serveur MCP, puis demandez : « Upscale approved-source.mp4 to 1080p with Video Upscaler. » Il téléverse le fichier avec spicyapi_upload_file, appelle spicyapi_task_create, qui s'arrête pour votre confirmation du prix, puis spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installe l'Agent Skill, qui fait lire le schéma réel du modèle par un assistant de code au lieu de deviner les champs.

Vérifiez le résultat par rapport à la source

Exécutez la même sonde sur les deux fichiers et comparez. Voici un script rapide qui affiche une ligne par clip :

probe() {
  ffprobe -v error -of json \
    -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration "$1" |
  jq -c '{size_bytes: (.format.size|tonumber), duration: (.format.duration|tonumber),
    video: (.streams|map(select(.codec_type=="video"))[0]|{codec:.codec_name,w:.width,h:.height,fps:.avg_frame_rate}),
    audio: (.streams|map(select(.codec_type=="audio"))[0]|if .==null then null else {codec:.codec_name,rate:.sample_rate,ch:.channels} end)}'
}
probe approved-source.mp4
probe returned.mp4

Ce qu'il faut confirmer :

1. Taille et format. Le rapport d'aspect correspond à la source et les dimensions sont celles que le palier devrait donner. Notez la largeur et la hauteur réelles ; ne les recopiez pas depuis le nom du palier.
2. Durée. La durée correspond à la source. Si votre destination dépend de points de coupe exacts, vérifiez la première et la dernière image, pas seulement un chiffre arrondi.
3. Audio. Le fichier renvoyé possède un flux audio avec le même nombre de canaux et la même longueur que la source. L'existence d'un flux ne prouve pas qu'il est correct, alors lisez les deux fichiers aux mêmes points : le premier mot prononcé, une coupe, la dernière phrase. Si la source était volontairement muette, le résultat doit l'être aussi.
4. Image en mouvement. Regardez tout le clip à vitesse normale avant d'inspecter des images fixes. Le scintillement, les textures qui fourmillent et les halos autour des bords en mouvement se voient en lecture et rarement sur une image fixe.
5. Détail qui porte du sens. Les étiquettes de produit, les logos, le texte et les visages sont les endroits où un agrandisseur peut inventer un détail plausible au lieu de récupérer un vrai détail. Comparez-les à la source sur le même cadrage. Une marque modifiée fait échouer le clip, aussi nette soit-elle à l'écran.

Pour comparer un instant côte à côte, avec la source agrandie à la taille de sortie par plus proche voisin afin de voir ses vrais pixels :

ffmpeg -ss 2.0 -i returned.mp4 -ss 2.0 -i approved-source.mp4 \
  -filter_complex "[1:v]scale=1896:1094:flags=neighbor[s];[s][0:v]hstack" \
  -frames:v 1 compare-at-2s.png

Réglez l'échelle sur la largeur et la hauteur renvoyées.

Exportez le fichier de livraison exact

Quand la destination exige une toile fixe, terminez par un export local. L'exemple suppose une source approximativement verticale comme 2:3 ; un paysage agrandi puis complété par des marges jusqu'à 1080x1920 laisse une fine bande d'image. Les marges conservent toute l'image ; le recadrage remplit le cadre mais coupe les bords, alors regardez le produit après l'un ou l'autre.

ffmpeg -i accepted-upscale.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -c:a aac -b:a 192k delivery-vertical.mp4

Cela réencode l'audio. Si vous avez besoin de la piste d'origine intacte, utilisez -c:a copy quand la destination l'accepte, puis relancez la sonde sur le fichier exporté. Incrustez les sous-titres et les graphiques après l'agrandissement, afin que les bords des lettres soient dessinés à la taille finale plutôt qu'agrandis.

Conservez trois fichiers : la source validée, l'agrandissement intact et chaque export. Un recadrage ou une réexportation ultérieur ne coûtera alors jamais une seconde passe d'agrandissement.

Quand quelque chose se passe mal

Corrigez l'étape qui a échoué au lieu de relancer l'agrandissement.

Un essai pilote avant un lot

Passez un clip qui a un vrai mouvement et une piste audio par tout le parcours : sonde, agrandissement, téléchargement, comparaison, export, puis lisez le fichier final dans la destination réelle (le flux, le lecteur, le grand écran). Les lecteurs locaux et les plateformes décodent et recompressent différemment, donc seule la destination montre si le résultat tient. Pour un lot, incluez un panoramique rapide, une publicité riche en coupes et un clip à texture fine, et notez pour chaque clip la durée source, les secondes facturées, le palier, le débit final et la raison d'un éventuel rejet.

Si vous comparez des paliers, gardez le clip constant et comparez 1080p et 4K à la taille à laquelle il sera visionné. Si 1080p suffit déjà à la destination, les $0.018 supplémentaires par seconde n'apportent rien de visible.

La décision

Considérez le fichier renvoyé comme un master à vérifier, pas comme une livraison finie. L'appel coûte quelques centimes ; les coûts évitables sont de refaire le montage à plus haute résolution, d'agrandir un clip déjà assez grand et d'expédier un fichier dont l'audio ou l'étiquette de produit a changé. Ouvrez la page du modèle Video Upscaler pour essayer un clip.