Рабочий процесс Foley API: добавляем и проверяем звук для видео

Чтобы добавить звуковые эффекты к готовому немому клипу, отправьте его MP4 в Foley v1, указав длину клипа и короткий список того, что должно быть слышно. Цена составляет $0.0012 за запрошенную секунду: шестисекундный клип стоит $0.0072, а запрос по умолчанию на восемь секунд — $0.0096. Вы получаете тот же видеоклип с прикреплённой сгенерированной звуковой дорожкой, а не отдельный аудиофайл, и любой звук во входном клипе заменяется. Задача обычно выполняется меньше чем за минуту.

Когда Foley — правильный шаг

Используйте его, когда картинка уже финальная и немая: вывод видеомодели без звука, продуктовый цикл, черновой монтаж, который трудно оценить без звука. Он создаёт эффекты и фоновую атмосферу (шаги, чашки, дождь, движение транспорта, кухню), а не музыку, и речь выходит в лучшем случае бормотанием. Если ваша видеомодель умеет генерировать звук вместе с изображением, запросите его там; Foley нужен для клипов, которые вы не можете или не хотите генерировать заново. Для произносимых реплик используйте Lip Sync или Talking Avatar; эффекты добавляйте так, как описано в разделе про диалог ниже.

Подготовьте клип

Берите финальный план, а не длинную сборку с неиспользованным материалом. Для шестисекундной сцены, где вымышленный взрослый человек ставит керамическую чашку на деревянный стол, включите приближение руки, видимое касание и момент покоя. Это касание и есть ваш ориентир по таймингу. Смонтажная склейка на другой ракурс в середине сцены добавляет вторую границу события и затрудняет диагностику плохого результата.

Используйте MP4 размером до 90 МБ: прямую ссылку на файл (не страницу для обмена) или файл, загруженный с вашего компьютера (файлы .mov конвертируются в MP4 при загрузке; см. Media). Сохраните оригинал, потому что возвращённый файл содержит только новую дорожку.

Сначала попробуйте в Playground

Откройте Video Sound Effects на вкладке Playground в режиме Form и войдите в аккаунт с балансом, чтобы запустить выполнение.

1. Перетащите MP4 в поле Input video (или вставьте ссылку в Asset URL и нажмите Add URL).

1. Опишите в Prompt нужные звуки коротким списком. Для чернового прогона оставьте поле пустым.
2. Задайте в Duration длину клипа в секундах.
3. Откройте Advanced parameters и впишите "music, speech" в Negative prompt.
4. Запустите модель и просмотрите возвращённый клип со звуком.

Меняйте по одному параметру за попытку и исправляйте промпт перед повтором, потому что каждый завершённый запуск тарифицируется.

Параметры и что не трогать

| Поле | Допустимое значение | Начальное значение |

| --- | --- | --- | | video_url (Input video) | MP4, до 90 МБ | Прямая ссылка на финальный клип | | duration_seconds (Duration) | Целое 1-30, по умолчанию 8 | Длина клипа с округлением вверх | | prompt (Prompt) | Необязательно, 1-1,000 символов | Три или четыре источника звука | | negative_prompt (Negative prompt) | До 1,000 символов | Music, speech | | guidance_scale (Prompt adherence) | 0-20, по умолчанию 4.5 | Не менять | | steps (Sampling steps) | 4-50, по умолчанию 25 | Не менять | | ignore_visual_semantics (Sound from prompt only) | Логическое значение, по умолчанию false | false | duration_seconds — это то, за что вы платите, а не длина клипа. Шестисекундный клип, отправленный с умолчательными восемью секундами, тарифицируется за восемь и возвращается с шестью секундами звука; десятисекундный клип с duration_seconds: 6 возвращается обрезанным до шести. Подстройте значение под клип. Клип длиннее 30 секунд приходится разрезать на части по 30 секунд или меньше по монтажной склейке, выполнить их отдельно и соединить дорожки в редакторе; каждая часть тарифицируется по своим секундам.

ignore_visual_semantics: true выбирает звуки из промпта, а не из картинки, при этом тайминг по-прежнему задаёт движение. Используйте его для звука, которого нет в кадре, например далёкого гула за окном. Это не решение для звука чашки, который звучит чуть поздно, и на цену он не влияет. Увеличивайте guidance_scale лишь в том случае, если результат игнорирует ваш промпт. Параметра seed нет.

Как писать промпт

Перечисляйте, что издаёт звук, а не настроение: "espresso machine hiss, cups clinking, low café chatter" работает, "cosy atmosphere" — нет. Называйте материал и характер касания ("ceramic cup on wood, soft contact") и описывайте только то, что видно в кадре. Просьба о шагах в плане, где человек лишь поворачивает голову, даёт правдоподобный, но несинхронный звук. Для чернового прогона промпт опускайте: тогда модель сама сопоставит звуки с действием.

Два стартовых промпта:

• Чашка на столе: "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." Негативный: "speech, music, repeated clattering, metallic ringing, crowd noise".

• Три медленных шага, полностью одетый человек: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Если шаги звучат как каблуки, назовите подошву и поверхность; если они просто слишком громкие, приглушите дорожку в редакторе.

Быстрые повторяющиеся действия — трудный случай: карандаш, скребущий с постоянной скоростью, или быстро листаемые страницы редко попадают точно по каждому штриху. Сначала сгенерируйте основу, затем вручную поставьте один чистый сэмпл в нужном ритме или позвольте фоновой атмосфере это закрыть.

Затем запустите из кода

Тот же запрос в коде. Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY в окружении сервера и выполните:

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

Ссылка на результат подписана и действует около 20 минут, а файл хранится 14 дней, поэтому сразу скопируйте его в собственное хранилище. Расчёт цены, ожидание, загрузка, повторные попытки и коды ошибок разобраны в руководстве по задачам и справочнике Python SDK.

Или пусть запустит Agent

Если обработкой клипов должен заниматься ассистент, все три официальных инструмента показывают цену и запрашивают подтверждение перед платным вызовом.

• CLI. Загрузите клип, положите возвращённый URI spicy:// и промпт в input.json, затем:

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

Смотрите документацию по CLI; npx @spicyapi/cli работает без установки.

• MCP-сервер. Добавьте MCP-сервер к ассистенту и запросите: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Он вызывает spicyapi_upload_file для файла с вашего компьютера, затем spicyapi_task_create, который останавливается для подтверждения цены, затем spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, благодаря которому ассистент по программированию читает актуальную схему модели, а не угадывает поля.

Проверка: материал, количество, тайминг

Просмотрите картинку со звуком на обычной скорости, а затем перемотайте касание в замедлении. Три типа ошибок требуют разных исправлений:

• Неверный материал (металлический лязг для керамической чашки): замените "object impact" на "ceramic cup on wood, soft contact".

• Слишком много событий (несколько ударов на одно касание): попросите один-единственный звук постановки и уберите слова вроде rattling или clattering. Больше шагов не исправит это надёжно; упростите промпт или оставьте одно удачное касание, а остальное вырежьте.
• Неверный момент: измерьте ошибку больше чем в одном событии. Постоянное смещение устраняется небольшой подстройкой в редакторе. Ошибка, растущая по ходу клипа, — это дрейф, и однократное сдвигание всей дорожки её не исправит. Для плана с единственным касанием перетаскивание начала до кадра касания обычно быстрее, чем ещё одна попытка.

Тихие и деликатные сцены (дождь, клавиатура, мягкие шаги) — место, где дорожка чаще всего возвращается слишком тонкой; назовите звук как близкий и отчётливый или подложите под него фоновую атмосферу из звуковой библиотеки.

Клипы с диалогом и синхронизацией губ

Foley и Lip Sync каждый записывают собственную аудиодорожку и заменяют дорожку клипа, поэтому сцена с речью требует двух проходов. Сначала запустите Foley на немой картинке и извлеките её звуковую дорожку одним смешанным WAV (чашка, одежда и шум комнаты — не отдельные стемы; FFmpeg stream selection):

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

Затем запустите Lip Sync или Talking Avatar для голоса и подмешайте WAV из Foley под речь:

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

Эта команда сохраняет всё входное видео; duration=first заставляет смешанный звук следовать за первой входной аудиодорожкой. Добавляйте -shortest только если хотите обрезать картинку вместе с окончанием этого звука. Дорожка Foley не зацикливается автоматически: если Lip Sync повторяет картинку, расставьте или повторите эффекты на новых касаниях вручную либо запустите Foley на уже зацикленной финальной картинке.

Подстройте volume=0.35 на слух. Касание чашки, попавшее на значимый согласный, требует более низкого уровня или другой точки монтажа, а эффект, который в одиночку звучит тихо, может выделяться в паузе. Делайте фейд на тихой границе и сохраняйте нетронутой начальную атаку касания: фейд через него превращает удар в глухой стук.

Стоимость

Один базовый запуск плюс два альтернативных промпта на шестисекундном клипе стоят $0.0216; десять шестисекундных клипов по одному дублю обходятся в $0.072. Завершённый запрос тарифицируется независимо от того, как звучит результат, поэтому исправьте промпт перед повтором.

Для первого полезного результата: закончите монтаж картинки, назовите настоящий материал и касание, запросите точную длину клипа, а затем исправьте ошибки материала в промпте, а небольшие сдвиги тайминга — в редакторе. Это даёт более ясный следующий шаг, чем повторная просьба о "better cinematic sound".

FAQ

Можно ли сохранить диалог, который уже есть в моём клипе? Нет, результат Foley не содержит его: возвращённое видео несёт только сгенерированную дорожку. Подмешайте исходное аудио обратно в редакторе.

Он делает музыку или голоса? Нет. Укажите музыку и речь в negative_prompt; тем не менее может появиться бормотание, похожее на речь, поэтому прослушайте результат перед сдачей.