Foley API Workflow: Sound für Video hinzufügen und prüfen

Um einem fertigen, stummen Clip Soundeffekte hinzuzufügen, senden Sie sein MP4 zusammen mit der Clip-Länge und einer kurzen Liste dessen, was zu hören sein soll, an Foley v1. Der Preis beträgt $0.0012 pro angeforderter Sekunde: Ein sechssekündiger Clip kostet $0.0072, die Standardanfrage von acht Sekunden $0.0096. Sie erhalten dasselbe Video mit angehängtem generiertem Soundtrack, keine separate Audiodatei, und jeder Ton, den der Eingangsclip mitbrachte, wird ersetzt. Ein Task ist meist in unter einer Minute fertig.

Wann Foley der richtige Schritt ist

Nutzen Sie ihn, wenn das Bild bereits final und stumm ist: die Ausgabe eines Videomodells ohne Ton, eine Produktschleife, ein Rohschnitt, der ohne Sound schwer zu beurteilen ist. Erzeugt werden Effekte und Ambiente (Schritte, Tassen, Regen, Verkehr, eine Küche), keine Musik, und Sprache kommt bestenfalls als Murmeln heraus. Wenn Ihr Videomodell Sound mit dem Bild erzeugen kann, fordern Sie ihn dort an; Foley ist für Clips, die Sie nicht neu generieren können oder wollen. Für gesprochene Zeilen verwenden Sie Lip Sync oder Talking Avatar; Effekte fügen Sie wie im Dialogabschnitt unten beschrieben hinzu.

Den Clip vorbereiten

Verwenden Sie die finale Einstellung, nicht eine längere Zusammenstellung mit ungenutztem Material. Für eine sechssekündige Szene, in der eine erfundene erwachsene Figur eine Keramiktasse auf einen Holzschreibtisch stellt, nehmen Sie die Annäherung der Hand, den sichtbaren Kontakt und einen Moment Ruhe auf. Der Kontakt ist Ihr zeitlicher Bezugspunkt. Ein Schnitt auf eine andere Perspektive in der Mitte fügt eine zweite Ereignisgrenze hinzu und macht ein schlechtes Ergebnis schwerer zu diagnostizieren.

Verwenden Sie ein MP4 bis zu 90 MB: einen direkten Link auf die Datei (keine Freigabeseite) oder eine Datei, die Sie von Ihrem Rechner hochladen (.mov-Dateien werden beim Hochladen in MP4 konvertiert; siehe Media). Behalten Sie das Original, weil die zurückgegebene Datei nur die neue Spur enthält.

Erst im Playground ausprobieren

Öffnen Sie Video Sound Effects im Tab Playground in der Ansicht Form und melden Sie sich mit einem Konto mit Guthaben an, um zu starten.

1. Ziehen Sie Ihr MP4 auf das Feld unter Input video (oder fügen Sie den Link unter Asset URL ein und drücken Sie Add URL).
2. Schreiben Sie in Prompt die gewünschten Klänge als kurze Liste. Lassen Sie das Feld für einen groben Durchgang leer.
3. Setzen Sie Duration auf die Länge Ihres Clips in Sekunden.
4. Öffnen Sie Advanced parameters und setzen Sie "music, speech" in Negative prompt.
5. Starten Sie das Modell und geben Sie den zurückgegebenen Clip mit Ton wieder.

Ändern Sie pro Versuch nur eine Sache und korrigieren Sie den Prompt vor dem Wiederholen, denn jeder abgeschlossene Lauf wird berechnet.

Steuerung und was Sie in Ruhe lassen sollten

duration_seconds ist das, was Sie bezahlen, nicht die Clip-Länge. Ein sechssekündiger Clip, der mit den Standard acht Sekunden gesendet wird, wird für acht berechnet und kommt sechs Sekunden lang zurück; ein zehnsekündiger Clip mit duration_seconds: 6 kommt auf sechs gekürzt zurück. Passen Sie es an den Clip an. Ein Clip länger als 30 Sekunden muss an einem Szenenwechsel in Stücke von 30 Sekunden oder weniger geschnitten, einzeln verarbeitet und in Ihrem Editor zusammengeführt werden; jedes Stück wird nach seinen eigenen Sekunden berechnet.

ignore_visual_semantics: true wählt die Klänge aus dem Prompt statt aus dem Bild, während die Bewegung weiterhin das Timing vorgibt. Nutzen Sie es für einen Klang, der nicht im Bild ist, etwa ein fernes Summen hinter einer Fensteraufnahme. Es ist keine Abhilfe für ein Tassengeräusch, das etwas zu spät kommt, und es ändert den Preis nicht. Erhöhen Sie guidance_scale nur leicht, wenn das Ergebnis Ihren Prompt ignoriert. Einen Seed gibt es nicht.

Den Prompt schreiben

Listen Sie auf, was Lärm macht, nicht die Stimmung: "espresso machine hiss, cups clinking, low café chatter" funktioniert; "cosy atmosphere" nicht. Nennen Sie das Material und den Kontakt ("ceramic cup on wood, soft contact") und beschreiben Sie nur, was das Bild zeigt. Schritte in einer Einstellung anzufordern, in der die Person nur den Kopf dreht, erzeugt plausible, aber nicht synchronisierte Klänge. Lassen Sie den Prompt für einen groben Durchgang weg; das Modell ordnet die Klänge dann der Handlung zu.

Zwei Startprompts:

• Tasse auf einem Schreibtisch: "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." Negativ: "speech, music, repeated clattering, metallic ringing, crowd noise".
• Drei langsame Schritte, vollständig bekleidet: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Klingt der Schritt wie ein Absatz, nennen Sie die Sohle und den Untergrund; ist er nur zu laut, senken Sie die Spur im Editor.

Schnelle, sich wiederholende Bewegungen sind der schwierige Fall: Ein mit konstanter Geschwindigkeit kratzender Stift oder schnell blätternde Seiten treffen selten Zug für Zug. Erzeugen Sie zuerst die Grundlage und setzen Sie dann ein sauberes Sample von Hand im richtigen Rhythmus, oder lassen Sie das Ambiente es überdecken.

Dann aus dem Code ausführen

Dieselbe Anfrage im Code. Installieren Sie das Python SDK (pip install spicyapi), setzen Sie SPICY_API_KEY in Ihrer Serverumgebung und führen Sie aus:

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

Der Ergebnislink ist signiert und gilt etwa 20 Minuten, die Datei wird 14 Tage aufbewahrt, also kopieren Sie sie sofort in Ihren eigenen Speicher. Preisangebote, Warten, Download, Wiederholungen und Fehlercodes behandeln der Tasks-Leitfaden und die Python-SDK-Referenz.

Oder einen Agenten laufen lassen

Wenn ein Assistent die Clips verarbeiten soll, zeigen alle drei offiziellen Tools den Preis und fragen Sie vor einem kostenpflichtigen Aufruf nach der Bestätigung.

• CLI. Laden Sie den Clip hoch, legen Sie die zurückgegebene spicy:// URI und Ihren Prompt in input.json und führen Sie dann aus:

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

Siehe CLI-Doku; npx @spicyapi/cli funktioniert ohne Installation.

• MCP-Server. Fügen Sie Ihrem Assistenten den MCP-Server hinzu und fragen Sie dann: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Er ruft spicyapi_upload_file für eine Datei auf Ihrem Rechner auf, dann spicyapi_task_create, das für Ihre Preisbestätigung anhält, dann spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installiert den Agent Skill, der einen Coding-Assistenten das aktuelle Modell-Schema lesen lässt, statt Felder zu raten.

Prüfen: Material, Anzahl, Timing

Spielen Sie das Bild mit Ton in normaler Geschwindigkeit ab und wiederholen Sie den Kontakt langsam. Die drei Fehlerfälle brauchen unterschiedliche Korrekturen:

• Falsches Material (ein metallischer Schlag für eine Keramiktasse): ersetzen Sie "object impact" durch "ceramic cup on wood, soft contact".
• Zu viele Ereignisse (mehrere Aufschläge für einen Kontakt): fordern Sie ein einzelnes Aufsetzen an und streichen Sie Wörter wie rattling oder clattering. Mehr Schritte beheben das nicht verlässlich; vereinfachen Sie den Prompt oder behalten Sie den einen guten Kontakt und schneiden Sie den Rest heraus.
• Falscher Zeitpunkt: Messen Sie den Fehler an mehr als einem Ereignis. Ein konstanter Versatz ist eine kleine Verschiebung im Editor. Ein Fehler, der über den Clip hinweg wächst, ist Drift, und ein einmaliges Verschieben der ganzen Spur behebt ihn nicht. Bei einer Einstellung mit einem einzigen Kontakt ist es meist schneller, den Einsatz auf den Kontaktframe zu ziehen, als einen weiteren Versuch zu starten.

Leise oder empfindliche Szenen (Regen, Tippen, weiche Schritte) sind der Ort, an dem eine Spur am dünnsten zurückkommt; benennen Sie den Klang als nah und prominent, oder legen Sie ein Ambiente aus einer Soundbibliothek darunter.

Dialog und Lip-Sync-Clips

Foley und Lip Sync schreiben jeweils ihre eigene Audiospur und ersetzen die des Clips, daher braucht eine sprechende Szene zwei Durchläufe. Führen Sie zuerst Foley auf dem stummen Bild aus und extrahieren Sie die Tonspur als eine einzige gemischte WAV-Datei (Tasse, Kleidung und Raumton sind keine getrennten Stems; FFmpeg Stream Selection):

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

Führen Sie dann Lip Sync oder Talking Avatar für die Stimme aus und mischen Sie die Foley-WAV unter die Sprache:

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

Dieser Befehl behält das vollständige Eingabevideo; duration=first lässt den gemischten Ton der ersten Eingabespur folgen. Fügen Sie -shortest nur hinzu, wenn Sie das Bild abschneiden wollen, wenn dieser Ton endet. Die Foley-Spur loopt nicht automatisch: Wenn Lip Sync das Bild wiederholt, setzen Sie die Effekte an den neuen Kontaktpunkten selbst oder wiederholen Sie sie dort, oder führen Sie Foley auf dem fertigen geloopten Bild aus.

Passen Sie volume=0.35 nach Gehör an. Ein Tassenkontakt, der auf einem Konsonanten landet, braucht einen niedrigeren Pegel oder einen anderen Schnittpunkt, und ein Effekt, der allein leise klingt, kann in einer Pause herausstehen. Blenden Sie an einer leisen Grenze aus und lassen Sie den Kontaktimpuls intakt; ein Ausblenden darüber verwandelt einen Aufschlag in ein weiches Pochen.

Kosten

Ein Basislauf plus zwei alternative Prompts auf einem sechssekündigen Clip kosten $0.0216; zehn sechssekündige Clips mit je einem Take kosten $0.072. Eine abgeschlossene Anfrage wird berechnet, egal wie das Ergebnis klingt, also korrigieren Sie den Prompt vor dem Wiederholen.

Für ein erstes brauchbares Ergebnis: Schließen Sie den Bildschnitt ab, benennen Sie das echte Material und den echten Kontakt, fordern Sie exakt die Clip-Länge an und beheben Sie dann Materialfehler im Prompt sowie kleine Timing-Abweichungen im Editor. Das gibt Ihnen einen klareren nächsten Schritt, als noch einmal nach "better cinematic sound" zu fragen.

FAQ

Kann ich den Dialog behalten, der schon in meinem Clip ist? Nicht innerhalb der Foley-Ausgabe: das zurückgegebene Video trägt nur die generierte Spur. Mischen Sie das Originalaudio in Ihrem Editor wieder hinein.

Erzeugt er Musik oder Stimmen? Nein. Setzen Sie Musik und Sprache in negative_prompt; sprachähnliches Murmeln kann trotzdem auftauchen, also prüfen Sie vor der Auslieferung.