Przepływ pracy Foley API: dodaj i sprawdź dźwięk do filmu

Aby dodać efekty dźwiękowe do gotowego, niemego klipu, wyślij jego MP4 do Foley v1 wraz z długością klipu i krótką listą tego, co powinno być słyszalne. Cena wynosi 0,0012 $ za każdą żądaną sekundę: sześciosekundowy klip kosztuje 0,0072 $, a domyślne żądanie ośmiosekundowe kosztuje 0,0096 $. Dostajesz ten sam film z dołączonym wygenerowanym podkładem dźwiękowym, a nie osobny plik audio, a cały dźwięk obecny w klipie wejściowym zostaje zastąpiony. Zadanie zwykle kończy się w mniej niż minutę.

Kiedy Foley jest właściwym krokiem

Użyj go, gdy obraz jest już finalny i niemy: wynik modelu wideo bez dźwięku, pętla produktowa, montaż roboczy, który trudno ocenić bez dźwięku. Generuje efekty i tło dźwiękowe (kroki, filiżanki, deszcz, ruch uliczny, kuchnia), a nie muzykę, a mowa wychodzi najwyżej jako mamrotanie. Jeśli Twój model wideo potrafi generować dźwięk razem z obrazem, poproś o niego tam; Foley jest dla klipów, których nie możesz albo nie chcesz generować od nowa. Dla wypowiadanych kwestii użyj Lip Sync lub Talking Avatar; efekty dodaj tak, jak opisano w sekcji o dialogu poniżej.

Przygotuj klip

Użyj finalnego ujęcia, a nie dłuższego montażu z niewykorzystanym materiałem. W scenie trwającej sześć sekund, w której fikcyjna dorosła osoba kładzie ceramiczny kubek na drewnianym biurku, uwzględnij zbliżanie się dłoni, widoczny kontakt i chwilę spokoju. Ten kontakt jest Twoim punktem odniesienia dla czasu. Cięcie na inny kąt w połowie sceny dodaje drugą granicę zdarzeń i utrudnia rozpoznanie złego wyniku.

Użyj pliku MP4 o rozmiarze do 90 MB: bezpośredniego linku do pliku (nie strony udostępniania) albo pliku wgrywanego z komputera (pliki .mov są konwertowane do MP4 podczas wgrywania; zobacz Media). Zachowaj oryginał, ponieważ zwrócony plik zawiera tylko nową ścieżkę.

Najpierw wypróbuj w Playground

Otwórz Video Sound Effects w zakładce Playground, w widoku Form, i zaloguj się kontem z saldem, aby uruchomić.

1. Upuść plik MP4 na polu Input video (albo wklej jego link w Asset URL i naciśnij Add URL).

1. Wpisz w Prompt pożądane dźwięki jako krótką listę. Dla szybkiego przebiegu zostaw pole puste.
2. Ustaw Duration na długość klipu w sekundach.
3. Otwórz Advanced parameters i wpisz "music, speech" w Negative prompt.
4. Uruchom model i odtwórz zwrócony klip z dźwiękiem.

Na jedno podejście zmieniaj tylko jedną rzecz i popraw prompt przed ponowną próbą, bo każde zakończone uruchomienie jest rozliczane.

Parametry i to, czego nie należy ruszać

| Pole | Dozwolone wejście | Wartość początkowa |

| --- | --- | --- | | video_url (Input video) | MP4, do 90 MB | Bezpośredni URL finalnego klipu | | duration_seconds (Duration) | Liczba całkowita 1-30, domyślnie 8 | Długość klipu zaokrąglona w górę | | prompt (Prompt) | Opcjonalnie, 1-1,000 znaków | Trzy lub cztery źródła dźwięku | | negative_prompt (Negative prompt) | Do 1,000 znaków | Music, speech | | guidance_scale (Prompt adherence) | 0-20, domyślnie 4.5 | Nie zmieniać | | steps (Sampling steps) | 4-50, domyślnie 25 | Nie zmieniać | | ignore_visual_semantics (Sound from prompt only) | Wartość logiczna, domyślnie false | false | To duration_seconds jest tym, za co płacisz, a nie długość klipu. Sześciosekundowy klip wysłany z domyślnymi ośmioma sekundami jest rozliczany jak osiem i wraca z sześcioma sekundami; dziesięciosekundowy klip z duration_seconds: 6 wraca ucięty do sześciu. Dopasuj tę wartość do klipu. Klip dłuższy niż 30 sekund trzeba pociąć na części po 30 sekund lub krótsze w miejscu zmiany sceny, wykonać osobno, a ścieżki połączyć w edytorze; każda część jest rozliczana według własnych sekund.

ignore_visual_semantics: true wybiera dźwięki z promptu zamiast z obrazu, ale czas nadal wyznacza ruch. Użyj tego dla dźwięku, którego nie ma w kadrze, na przykład odległego buczenia za oknem. To nie jest rozwiązanie dźwięku kubka, który brzmi trochę za późno, i nie zmienia ceny. Zwiększ guidance_scale tylko wtedy, gdy wynik ignoruje Twój prompt. Nie ma parametru seed.

Pisanie promptu

Wymieniaj to, co wydaje dźwięk, a nie nastrój: "espresso machine hiss, cups clinking, low café chatter" działa, "cosy atmosphere" nie. Podaj materiał i kontakt ("ceramic cup on wood, soft contact") oraz opisz wyłącznie to, co widać w kadrze. Proszenie o kroki w ujęciu, w którym postać tylko odwraca głowę, daje dźwięk wiarygodny, ale niesynchronizowany. Przy szybkim przebiegu pomiń prompt; model sam dopasuje dźwięki do akcji.

Dwa prompty na start:

• Kubek na biurku: "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." Negatywny: "speech, music, repeated clattering, metallic ringing, crowd noise".

• Trzy powolne kroki, w pełni ubrana osoba: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Jeśli kroki brzmią jak obcasy, podaj podeszwę i nawierzchnię; jeśli są po prostu za głośne, ścisz ścieżkę w edytorze.

Szybkie, powtarzalne ruchy to przypadek trudny: ołówek drapiący ze stałą prędkością czy szybko przewracane strony rzadko trafiają w każde pociągnięcie. Najpierw wygeneruj podstawę, potem ręcznie umieść jeden czysty sample w odpowiednim rytmie albo pozwól, by przykryło go tło dźwiękowe.

Potem uruchom to z kodu

To samo żądanie w kodzie. Zainstaluj Python SDK (pip install spicyapi), ustaw SPICY_API_KEY w środowisku serwera i uruchom:

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

Link do wyniku jest podpisany i ważny około 20 minut, a plik jest przechowywany przez 14 dni, więc od razu skopiuj go do własnej pamięci. Wyceny, oczekiwanie, pobieranie, ponowne próby i kody błędów opisuje przewodnik po zadaniach oraz referencja Python SDK.

Albo niech uruchomi to Agent

Gdy klipy ma przetwarzać asystent, wszystkie trzy oficjalne narzędzia pokazują cenę i pytają o zgodę przed płatnym wywołaniem.

• CLI. Wgraj klip, umieść zwrócony identyfikator spicy:// i swój prompt w input.json, a potem:

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

Zobacz dokumentację CLI; npx @spicyapi/cli działa bez instalowania.

• Serwer MCP. Dodaj serwer MCP do asystenta, a potem zapytaj: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Wywołuje spicyapi_upload_file dla pliku z Twojego komputera, następnie spicyapi_task_create, które zatrzymuje się w celu potwierdzenia ceny, a potem spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instaluje Agent Skill, który uczy asystenta programistycznego odczytywać aktualny schemat modelu zamiast zgadywać nazwy pól.

Sprawdzenie: materiał, liczba, czas

Odtwórz obraz z dźwiękiem w normalnej prędkości, potem powtórz kontakt w zwolnieniu. Te trzy błędy wymagają różnych poprawek:

• Zły materiał (metaliczny huk dla ceramicznego kubka): zastąp "object impact" przez "ceramic cup on wood, soft contact".

• Za dużo zdarzeń (kilka uderzeń przy jednym kontakcie): poproś o pojedyncze odłożenie i usuń słowa takie jak rattling czy clattering. Więcej kroków nie naprawi tego niezawodnie; uprość prompt albo zostaw ten dobry kontakt, a resztę wytnij.
• Zły moment: zmierz błąd w więcej niż jednym zdarzeniu. Stałe przesunięcie to drobna korekta w edytorze. Błąd narastający wzdłuż klipu to dryf, a jednorazowe przesunięcie całej ścieżki go nie naprawi. Dla ujęcia z jednym kontaktem przeciągnięcie początku do klatki kontaktu jest zwykle szybsze niż kolejna próba.

Ciche i delikatne sceny (deszcz, stukanie w klawisze, miękkie kroki) to miejsce, gdzie ścieżka najczęściej wraca zbyt cienka; nazwij dźwięk jako bliski i wyraźny albo podłóż pod niego podkład z biblioteki dźwięków.

Klipy z dialogiem i synchronizacją ruchu ust

Foley i Lip Sync każdy zapisują własną ścieżkę audio i zastępują ścieżkę klipu, więc scena dialogowa wymaga dwóch przebiegów. Najpierw uruchom Foley na niemym obrazie i wyodrębnij jego podkład dźwiękowy jako jeden zmiksowany plik WAV (kubek, ubranie i dźwięk pomieszczenia to nie osobne stemy; FFmpeg stream selection):

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

Potem uruchom Lip Sync lub Talking Avatar dla głosu i zmiksuj WAV z Foley pod mowę:

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

To polecenie zachowuje cały wejściowy film; duration=first sprawia, że zmiksowany dźwięk podąża za pierwszą wejściową ścieżką audio. Dodaj -shortest tylko wtedy, gdy chcesz ucinać obraz wraz z końcem tego dźwięku. Ścieżka Foley nie zapętla się automatycznie: jeśli Lip Sync powtarza obraz, rozmieść lub powtórz efekty w nowych punktach kontaktu albo uruchom Foley na gotowej zapętlonej wersji obrazu.

Dostosuj volume=0.35 na słuch. Kontakt kubka trafiający na ważną spółgłoskę wymaga niższego poziomu albo innego miejsca cięcia, a efekt, który sam w sobie brzmi cicho, może wybijać się w ciszy. Wygaszaj na cichej granicy i zachowaj w całości początkowe uderzenie (transjent) kontaktu; wygaszanie przez niego zamienia uderzenie w głuchy stuk.

Koszt

Jedno uruchomienie bazowe plus dwa alternatywne prompty na sześciosekundowym klipie kosztują 0,0216 $; dziesięć sześciosekundowych klipów po jednym ujęciu kosztuje 0,072 $. Zakończone żądanie jest rozliczane niezależnie od tego, jak brzmi wynik, więc popraw prompt przed ponowną próbą.

Aby uzyskać pierwszy użyteczny wynik: zakończ montaż obrazu, nazwij rzeczywisty materiał i kontakt, poproś o dokładną długość klipu, a potem popraw błędy materiału w prompcie, a małe przesunięcia czasu w edytorze. To daje jaśniejszy następny krok niż ponowne proszenie o "better cinematic sound".

FAQ

Czy mogę zachować dialog, który już jest w moim klipie? Nie w wyjściu Foley: zwrócony film zawiera tylko wygenerowaną ścieżkę. Wmieszaj oryginalne audio z powrotem w edytorze.

Czy tworzy muzykę albo głosy? Nie. Wpisz muzykę i mowę w negative_prompt; mimo to może pojawić się mamrotanie brzmiące jak mowa, więc odsłuchaj przed oddaniem.