Workflow Foley API: aggiungi e verifica l'audio di un video

Per aggiungere effetti sonori a un clip muto già finito, invia il suo MP4 a Foley v1 insieme alla durata del clip e a un breve elenco di ciò che dovrebbe essere udibile. Il prezzo è di $0.0012 per secondo richiesto: un clip di sei secondi costa $0.0072 e la richiesta predefinita di otto secondi costa $0.0096. Ricevi lo stesso video con la traccia audio generata integrata, non un file audio separato, e qualsiasi audio presente nel clip di input viene sostituito. Un task di solito termina in meno di un minuto.

Quando Foley è il passo giusto

Usalo quando l'immagine è già definitiva e muta: l'output di un modello video che non ha audio, un loop di prodotto, un montaggio provvisorio difficile da valutare senza il suono. Produce effetti e ambientazione (passi, tazze, pioggia, traffico, una cucina), non musica, e il parlato esce nel migliore dei casi come un mormorio. Se il tuo modello video può generare suono insieme all'immagine, chiedilo lì; Foley è per i clip che non puoi o non vuoi rigenerare. Per le battute parlate usa Lip Sync o Talking Avatar; aggiungi gli effetti come descritto nella sezione sul dialogo qui sotto.

Preparare il clip

Usa il piano finale, non un montaggio più lungo con materiale inutilizzato. Per una scena di sei secondi in cui una donna adulta fittizia appoggia una tazza di ceramica su una scrivania di legno, includi l'avvicinamento della mano, il contatto visibile e un momento di quiete. Il contatto è il tuo riferimento di timing. Un taglio a un altro angolo a metà scena aggiunge un secondo confine di evento e rende più difficile diagnosticare un risultato scarso.

Usa un MP4 fino a 90 MB: un link diretto al file (non una pagina di condivisione) oppure un file che carichi dal tuo computer (i file .mov vengono convertiti in MP4 durante il caricamento; vedi Media). Conserva l'originale, perché il file restituito contiene solo la nuova traccia.

Provalo prima nel Playground

Apri Video Sound Effects nella scheda Playground, in vista Form, e accedi con un account con saldo per eseguire.

1. Trascina il tuo MP4 sul campo sotto Input video (oppure incolla il link sotto Asset URL e premi Add URL).
2. Scrivi in Prompt i suoni che vuoi, come breve elenco. Lascia il campo vuoto per una passata rapida.
3. Imposta Duration sulla durata del clip in secondi.
4. Apri Advanced parameters e metti "music, speech" in Negative prompt.
5. Esegui il modello e riproduci il clip restituito con l'audio.

Cambia una sola cosa per tentativo e correggi il prompt prima di riprovare, perché ogni esecuzione completata viene fatturata.

I controlli e cosa lasciare in pace

duration_seconds è ciò che paghi, non la durata del clip. Un clip di sei secondi inviato con gli otto secondi predefiniti viene fatturato su otto e torna della durata di sei secondi; un clip di dieci secondi con duration_seconds: 6 torna tagliato a sei. Adattalo al clip. Un clip più lungo di 30 secondi deve essere tagliato in pezzi di 30 secondi o meno in corrispondenza di un cambio di scena, eseguito separatamente e con le tracce unite nel tuo editor; ogni pezzo viene fatturato sui propri secondi.

ignore_visual_semantics: true sceglie i suoni dal prompt invece che dall'immagine, mentre il movimento continua a determinare il timing. Usalo per un suono che non si vede, come un ronzio lontano dietro una ripresa di finestra. Non è una soluzione per il suono di una tazza che arriva un po' in ritardo, e non cambia il prezzo. Aumenta un po' guidance_scale solo se il risultato ignora il prompt. Non c'è un seed.

Scrivere il prompt

Elenca ciò che produce rumore, non l'atmosfera: "espresso machine hiss, cups clinking, low café chatter" funziona; "cosy atmosphere" no. Indica il materiale e il contatto ("ceramic cup on wood, soft contact") e descrivi solo ciò che l'immagine mostra. Chiedere passi in una ripresa in cui la persona gira solo la testa produce un suono plausibile ma non sincronizzato. Ometti il prompt per una passata rapida; il modello abbina allora i suoni all'azione.

Due prompt di partenza:

• Tazza su una scrivania: "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." Negativo: "speech, music, repeated clattering, metallic ringing, crowd noise".
• Tre passi lenti, con indumenti: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Se i passi suonano come tacchi, indica la suola e la superficie; se sono solo troppo forti, abbassa la traccia nell'editor.

Le azioni rapide e ripetitive sono il caso difficile: una matita che graffia a velocità costante o pagine sfogliate rapidamente raramente colgono tratto per tratto. Genera prima la base, poi inserisci a mano un campione pulito al ritmo giusto, oppure lascia che l'ambientazione lo copra.

Poi eseguila dal codice

La stessa richiesta in codice. Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY nell'ambiente del tuo server ed esegui:

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

Il link del risultato è firmato e vale circa 20 minuti e il file viene conservato per 14 giorni, quindi copialo subito nel tuo archivio. Preventivi di prezzo, attesa, download, nuovi tentativi e codici di errore sono trattati nella guida alle task e nel riferimento dell'SDK Python.

Oppure lascia che sia un Agent a eseguirla

Quando un assistente deve elaborare i clip, tutti e tre gli strumenti ufficiali mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento.

• CLI. Carica il clip, inserisci in input.json l'URI spicy:// restituito e il tuo prompt, poi:

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

Vedi la documentazione della CLI; npx @spicyapi/cli funziona senza installazione.

• Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Chiama spicyapi_upload_file per un file sul tuo computer, poi spicyapi_task_create, che si ferma per la conferma del prezzo, poi spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che insegna a un assistente di programmazione a leggere lo schema del modello in tempo reale invece di indovinare i campi.

Verificare: materiale, quantità, timing

Riproduci l'immagine con l'audio a velocità normale, poi rivedi il contatto al rallentatore. I tre errori richiedono correzioni diverse:

• Materiale sbagliato (un colpo metallico per una tazza di ceramica): sostituisci "object impact" con "ceramic cup on wood, soft contact".
• Troppi eventi (diversi impatti per un solo contatto): chiedi un unico posizionamento ed elimina parole come rattling o clattering. Più step non lo risolvono in modo affidabile; semplifica il prompt o tieni il buon contatto e ritaglia il resto.
• Momento sbagliato: misura l'errore su più di un evento. Uno scostamento costante è una piccola regolazione nell'editor. Un errore che cresce lungo il clip è deriva, e spostare l'intera traccia una volta non lo risolve. Per una ripresa con un solo contatto, trascinare l'attacco fino al frame del contatto è di solito più veloce di un altro tentativo.

Le scene tranquille o delicate (pioggia, digitazione, passi leggeri) sono quelle in cui una traccia torna più spesso sottile; indica il suono come vicino e prominente, oppure metti sotto un ambiente preso da una libreria sonora.

Clip con dialogo e sincronizzazione labiale

Foley e Lip Sync scrivono ciascuno la propria traccia audio e sostituiscono quella del clip, quindi una scena parlante richiede due passaggi. Esegui prima Foley sull'immagine muta ed estrai la sua traccia audio come un unico WAV mixato (la tazza, i vestiti e il suono della stanza non sono stem separati; FFmpeg stream selection):

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

Poi esegui Lip Sync o Talking Avatar per la voce e mixa il WAV di Foley sotto il parlato:

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

Questo comando conserva l'intero video di input; duration=first fa sì che l'audio mixato segua la prima traccia audio di input. Aggiungi -shortest solo se vuoi tagliare l'immagine quando quell'audio termina. La traccia Foley non si ripete automaticamente: se Lip Sync ripete l'immagine, inserisci o ripeti tu gli effetti nei nuovi punti di contatto, oppure esegui Foley sull'immagine finale già ripetuta in loop.

Regola volume=0.35 a orecchio. Un contatto di tazza che cade su una consonante chiave richiede un livello più basso o un punto di taglio diverso, e un effetto che da solo sembra sommesso può spiccare in una pausa. Applica una dissolvenza su un confine tranquillo e mantieni intatto il transitorio di contatto; dissolvere attraverso di esso trasforma un impatto in un tonfo ovattato.

Costo

Un'esecuzione di base più due prompt alternativi su un clip di sei secondi costa $0.0216; dieci clip da sei secondi con una ripresa ciascuno costano $0.072. Una richiesta completata viene fatturata comunque, qualunque cosa suoni il risultato, quindi correggi il prompt prima di riprovare.

Per un primo risultato utile: completa il montaggio dell'immagine, indica il materiale e il contatto reali, richiedi la durata esatta del clip, poi correggi gli errori di materiale nel prompt e i piccoli scostamenti di timing nell'editor. Così hai un passo successivo più chiaro che chiedere di nuovo un "better cinematic sound".

FAQ

Posso tenere il dialogo che è già nel mio clip? Non dentro l'output di Foley: il video restituito contiene solo la traccia generata. Rimixa l'audio originale nel tuo editor.

Genera musica o voci? No. Metti musica e parlato in negative_prompt; può comunque comparire un mormorio simile a voce, quindi ascolta prima della consegna.