Workflow Foley API : ajouter et vérifier le son d'une vidéo

Pour ajouter des effets sonores à un clip muet déjà terminé, envoyez son MP4 à Foley v1 avec la durée du clip et une courte liste de ce qui doit s'entendre. Le prix est de $0.0012 par seconde demandée : un clip de six secondes coûte $0.0072, et la demande par défaut de huit secondes coûte $0.0096. Vous récupérez la même vidéo avec la bande-son générée intégrée, pas un fichier audio séparé, et tout l'audio que le clip d'entrée contenait est remplacé. Une tâche se termine généralement en moins d'une minute.

Quand Foley est la bonne étape

Utilisez-le quand l'image est déjà définitive et muette : la sortie d'un modèle vidéo qui n'a pas d'audio, une boucle de produit, un montage brut difficile à juger sans le son. Il produit des effets et une ambiance (pas, tasses, pluie, circulation, une cuisine), pas de la musique, et la parole sort tout au plus comme un murmure. Si votre modèle vidéo peut générer du son avec l'image, demandez-le là-bas ; Foley est destiné aux clips que vous ne pouvez pas ou ne voulez pas régénérer. Pour les répliques parlées, utilisez Lip Sync ou Talking Avatar ; ajoutez les effets comme décrit dans la section sur le dialogue ci-dessous.

Préparer le clip

Utilisez le plan final, pas un montage plus long contenant des éléments inutilisés. Pour une scène de six secondes où une adulte fictive pose une tasse en céramique sur un bureau en bois, incluez l'approche de la main, le contact visible et un moment de pause. Le contact est votre repère de minutage. Une coupe vers un autre angle au milieu de la scène ajoute une seconde limite d'événement et rend plus difficile le diagnostic d'un mauvais résultat.

Utilisez un MP4 jusqu'à 90 Mo : un lien direct vers le fichier (pas une page de partage) ou un fichier que vous envoyez depuis votre ordinateur (les fichiers .mov sont convertis en MP4 pendant l'envoi ; voir Media). Conservez l'original, car le fichier renvoyé ne contient que la nouvelle piste.

Essayez d'abord dans le Playground

Ouvrez Video Sound Effects dans l'onglet Playground, en vue Form, et connectez-vous avec un compte approvisionné pour lancer l'exécution.

1. Déposez votre MP4 sur le champ sous Input video (ou collez son lien sous Asset URL et appuyez sur Add URL).
2. Écrivez dans Prompt les sons que vous voulez, sous forme de courte liste. Laissez le champ vide pour un passage approximatif.
3. Réglez Duration sur la durée de votre clip en secondes.
4. Ouvrez Advanced parameters et mettez « music, speech » dans Negative prompt.
5. Lancez le modèle et lisez le clip renvoyé avec son.

Changez une seule chose par essai et corrigez le prompt avant de réessayer, car chaque exécution terminée est facturée.

Les réglages et ce qu'il faut laisser tel quel

duration_seconds est ce que vous payez, pas la durée du clip. Un clip de six secondes envoyé avec les huit secondes par défaut est facturé sur huit et revient avec six secondes ; un clip de dix secondes avec duration_seconds: 6 revient coupé à six. Faites-le correspondre au clip. Un clip de plus de 30 secondes doit être découpé en morceaux de 30 secondes ou moins à un changement de scène, traité séparément, et les pistes assemblées dans votre montage ; chaque morceau est facturé sur ses propres secondes.

ignore_visual_semantics: true choisit les sons à partir du prompt plutôt que de l'image, tandis que le mouvement continue de piloter le minutage. Utilisez-le pour un son qui n'est pas à l'écran, comme un bourdonnement lointain derrière un plan de fenêtre. Ce n'est pas un correctif pour un bruit de tasse qui arrive un peu en retard, et cela ne change pas le prix. Augmentez légèrement guidance_scale uniquement si le résultat ignore votre prompt. Il n'y a pas de graine.

Rédiger le prompt

Listez ce qui fait du bruit, pas l'ambiance : « espresso machine hiss, cups clinking, low café chatter » fonctionne ; « cosy atmosphere » non. Nommez la matière et le contact (« ceramic cup on wood, soft contact ») et ne décrivez que ce que l'image montre. Demander des pas dans un plan où la personne ne fait que tourner la tête produit un son plausible mais désynchronisé. Omettez le prompt pour un passage approximatif ; le modèle associe alors les sons à l'action.

Deux prompts de départ :

• Tasse sur un bureau : « A ceramic cup is gently placed on a wooden desk. One soft ceramic contact at the visible touch, light sleeve rustle during the hand movement, quiet room tone. » Négatif : « speech, music, repeated clattering, metallic ringing, crowd noise ».
• Trois pas lents, habillé : « Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience. » Si les pas sonnent comme des talons, nommez la semelle et la surface ; s'ils sont seulement trop forts, baissez la piste dans le montage.

Les actions rapides et répétitives sont le cas difficile : un crayon qui gratte à vitesse constante ou des pages qui tournent rapidement tombent rarement trait par trait. Générez d'abord la couche de fond, puis placez à la main un échantillon propre au bon rythme, ou laissez l'ambiance le couvrir.

Puis exécutez-la depuis le code

La même requête en 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

clip = client.upload_file("six-second-cup-shot.mp4")  # or pass a direct MP4 link as video_url

task = client.create_task(
    model="spicyapi/foley-v1/video-to-audio",
    input_data={
        "video_url": clip["uri"],
        "duration_seconds": 6,  # billed per requested second: match the clip
        "prompt": "A ceramic cup is gently placed on a wooden desk. One soft ceramic contact at the "
                  "visible touch, light sleeve rustle during the hand movement, quiet room tone. "
                  "Natural close sound, no dramatic impact.",
        "negative_prompt": "speech, music, repeated clattering, metallic ringing, crowd noise",
    },
    idempotency_key=str(uuid.uuid4()),
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"])  # the same clip with sound; copy it now

Le lien du résultat est signé et valable environ 20 minutes, et le fichier est conservé 14 jours : copiez-le donc immédiatement dans votre propre stockage. Les devis de prix, l'attente, le téléchargement, les nouvelles tentatives et les codes d'erreur sont couverts dans le guide des tâches et la référence du SDK Python.

Ou laissez un Agent l'exécuter

Quand un assistant doit traiter les clips, les trois outils officiels affichent le prix et vous demandent confirmation avant un appel payant.

• CLI. Envoyez le clip, placez l'URI spicy:// renvoyée et votre prompt dans input.json, puis :

``bash spicyapi files upload six-second-cup-shot.mp4 spicyapi tasks create --model spicyapi/foley-v1/video-to-audio --input-file input.json --wait ``

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

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : « Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech. » Il appelle spicyapi_upload_file pour un fichier sur votre ordinateur, puis 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 apprend à un assistant de programmation à lire le schéma du modèle en direct au lieu de deviner les champs.

Vérifier : matière, nombre, minutage

Lisez l'image avec son à vitesse normale, puis rejouez le contact au ralenti. Les trois échecs exigent des corrections différentes :

• Mauvaise matière (un claquement métallique pour une tasse en céramique) : remplacez « object impact » par « ceramic cup on wood, soft contact ».
• Trop d'événements (plusieurs impacts pour un seul contact) : demandez un seul dépôt et retirez des mots comme rattling ou clattering. Davantage d'étapes ne le corrigera pas de façon fiable ; simplifiez le prompt ou gardez le bon contact et supprimez le reste au montage.
• Mauvais moment : mesurez l'erreur sur plus d'un événement. Un décalage constant se corrige par un léger ajustement dans le montage. Une erreur qui croît sur toute la durée du clip est une dérive, et déplacer la piste entière une fois ne la corrigera pas. Pour un plan à un seul contact, faire glisser le début sur l'image du contact est généralement plus rapide qu'un nouvel essai.

Les scènes calmes ou délicates (pluie, frappe au clavier, pas légers) sont celles où une piste revient le plus souvent ténue ; nommez le son comme proche et marquant, ou posez en dessous une ambiance tirée d'une bibliothèque sonore.

Clips de dialogue et de synchronisation labiale

Foley et Lip Sync écrivent chacun leur propre piste audio et remplacent celle du clip : une scène parlante demande donc deux passes. Lancez Foley sur l'image muette d'abord et extrayez sa bande-son en un seul WAV mélangé (la tasse, les vêtements et le bruit de la pièce ne sont pas des pistes séparées ; FFmpeg stream selection) :

ffmpeg -i foley-result.mp4 -map 0:a:0 -vn -c:a pcm_s16le foley-track.wav

Puis lancez Lip Sync ou Talking Avatar pour la voix et mixez le WAV de Foley sous la parole :

ffmpeg -i lipsync.mp4 -i foley-track.wav \
  -filter_complex "[1:a]volume=0.35[fx];[0:a][fx]amix=inputs=2:duration=first:normalize=0[a]" \
  -map 0:v -map "[a]" -c:v copy -c:a aac mixed.mp4

Cette commande conserve la vidéo d'entrée complète ; duration=first fait que l'audio mélangé suit la première piste audio d'entrée. N'ajoutez -shortest que si vous voulez couper l'image à la fin de cet audio. La piste Foley ne boucle pas automatiquement : si Lip Sync répète l'image, placez ou répétez les effets vous-même aux nouveaux contacts, ou lancez Foley sur l'image finale déjà bouclée.

Ajustez volume=0.35 à l'oreille. Un contact de tasse qui tombe sur une consonne importante demande un niveau plus bas ou un point de coupe différent, et un effet qui semble discret seul peut ressortir dans un silence. Faites un fondu sur une frontière calme et gardez le transitoire de contact intact ; un fondu le traversant transforme un impact en un bruit sourd.

Coût

Une exécution de base plus deux prompts alternatifs sur un clip de six secondes coûte $0.0216 ; dix clips de six secondes avec une prise chacun coûtent $0.072. Une requête terminée est facturée quel que soit le résultat, alors corrigez le prompt avant de réessayer.

Pour un premier résultat utile : terminez le montage de l'image, nommez la vraie matière et le vrai contact, demandez la durée exacte du clip, puis corrigez les erreurs de matière dans le prompt et les petits décalages de minutage dans le montage. Cela vous donne une étape suivante plus claire que de redemander un "better cinematic sound".

FAQ

Puis-je conserver le dialogue déjà présent dans mon clip ? Pas dans la sortie Foley : la vidéo renvoyée ne porte que la piste générée. Remélangez l'audio d'origine dans votre montage.

Est-ce qu'il fait de la musique ou des voix ? Non. Mettez la musique et la parole dans negative_prompt ; un murmure ressemblant à de la parole peut tout de même apparaître, donc écoutez avant la livraison.