Fluxo de trabalho da Foley API: adicione e revise o som de um vídeo

Para adicionar efeitos sonoros a um clipe mudo já finalizado, envie o MP4 dele ao Foley v1 junto com a duração do clipe e uma lista curta do que deve ser ouvido. O preço é $0.0012 por segundo pedido: um clipe de seis segundos custa $0.0072 e o pedido padrão de oito segundos custa $0.0096. Você recebe o mesmo vídeo com a trilha de som gerada anexada, não um arquivo de áudio separado, e qualquer áudio que o clipe de entrada tivesse é substituído. A tarefa costuma terminar em menos de um minuto.

Quando o Foley é o passo certo

Use quando a imagem já está final e muda: a saída de um modelo de vídeo que não tem áudio, um loop de produto, um corte bruto difícil de avaliar sem som. Ele produz efeitos e ambiência (passos, xícaras, chuva, trânsito, uma cozinha), não música, e a fala sai no máximo como murmúrio. Se o seu modelo de vídeo consegue gerar som junto com a imagem, peça lá; o Foley é para clipes que você não pode ou não quer gerar de novo. Para falas use Lip Sync ou Talking Avatar; adicione os efeitos como descrito na seção de diálogo abaixo.

Preparar o clipe

Use o plano final, não uma montagem mais longa com material não utilizado. Para uma cena de seis segundos em que uma adulta fictícia coloca uma xícara de cerâmica sobre uma mesa de madeira, inclua a aproximação da mão, o contato visível e um momento de pausa. O contato é sua referência de tempo. Um corte para outro ângulo no meio da cena adiciona um segundo limite de evento e dificulta mais o diagnóstico de um resultado ruim.

Use um MP4 de até 90 MB: um link direto para o arquivo (não uma página de compartilhamento) ou um arquivo enviado do seu computador (arquivos .mov são convertidos para MP4 durante o envio; veja Media). Guarde o original, porque o arquivo devolvido contém apenas a nova trilha.

Experimente primeiro no Playground

Abra Video Sound Effects na aba Playground, na visão Form, e entre com uma conta com saldo para executar.

1. Solte seu MP4 no campo Input video (ou cole o link em Asset URL e pressione Add URL).

1. Escreva em Prompt os sons que você quer, como uma lista curta. Deixe vazio para uma passada rápida.
2. Defina Duration com a duração do seu clipe em segundos.
3. Abra Advanced parameters e coloque "music, speech" em Negative prompt.
4. Execute o modelo e reproduza o clipe devolvido com som.

Mude uma coisa por tentativa e corrija o prompt antes de tentar de novo, porque toda execução concluída é cobrada.

Controles e o que deixar em paz

| Campo | Entrada permitida | Valor inicial |

| --- | --- | --- | | video_url (Input video) | MP4, até 90 MB | URL direta do clipe final | | duration_seconds (Duration) | Inteiro 1-30, padrão 8 | A duração do clipe, arredondada para cima | | prompt (Prompt) | Opcional, 1-1,000 caracteres | Três ou quatro fontes de som | | negative_prompt (Negative prompt) | Até 1,000 caracteres | Music, speech | | guidance_scale (Prompt adherence) | 0-20, padrão 4.5 | Não mexer | | steps (Sampling steps) | 4-50, padrão 25 | Não mexer | | ignore_visual_semantics (Sound from prompt only) | Booleano, padrão false | false | duration_seconds é o que você paga, não a duração do clipe. Um clipe de seis segundos enviado com os oito segundos padrão é cobrado por oito e volta com seis segundos; um clipe de dez segundos com duration_seconds: 6 volta cortado para seis. Ajuste ao clipe. Um clipe com mais de 30 segundos precisa ser cortado em pedaços de 30 segundos ou menos em uma mudança de cena, executado separadamente e com as trilhas unidas no seu editor; cada pedaço é cobrado pelos seus próprios segundos.

ignore_visual_semantics: true escolhe os sons a partir do prompt em vez da imagem, enquanto o movimento continua determinando o tempo. Use para um som que não está na tela, como um zumbido distante atrás de um plano de janela. Não é uma solução para o som de uma xícara que chega um pouco atrasado, e não muda o preço. Aumente um pouco o guidance_scale só se o resultado ignorar o seu prompt. Não há seed.

Escrever o prompt

Liste o que faz barulho, não o clima: "espresso machine hiss, cups clinking, low café chatter" funciona; "cosy atmosphere" não. Nomeie o material e o contato ("ceramic cup on wood, soft contact") e descreva apenas o que a imagem mostra. Pedir passos em um plano em que a pessoa só vira a cabeça produz um som plausível, mas fora de sincronia. Omita o prompt para uma passada rápida; o modelo então casa os sons com a ação.

Dois prompts iniciais:

• Xícara sobre a mesa: "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".

• Três passos lentos, com roupa: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Se os passos soarem como salto alto, nomeie o solado e a superfície; se estiverem apenas altos demais, abaixe a trilha no editor.

Ações rápidas e repetitivas são o caso difícil: um lápis riscando em velocidade constante ou páginas virando rápido raramente acertam traço por traço. Gere primeiro a base e depois coloque à mão uma amostra limpa no ritmo certo, ou deixe a ambiência cobrir.

Depois execute pelo código

A mesma requisição em código. Instale o SDK de Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor e execute:

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

O link do resultado é assinado e dura cerca de 20 minutos, e o arquivo é mantido por 14 dias, então copie para o seu armazenamento imediatamente. Cotações de preço, espera, downloads, novas tentativas e códigos de erro estão no guia de tasks e na referência do SDK Python.

Ou deixe um Agent executar

Quando um assistente deve processar os clipes, as três ferramentas oficiais mostram o preço e pedem confirmação antes de uma chamada paga.

• CLI. Envie o clipe, coloque no input.json o URI spicy:// devolvido e o seu prompt, e então:

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

Veja a documentação da CLI; npx @spicyapi/cli funciona sem instalar.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e então pergunte: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Ele chama spicyapi_upload_file para um arquivo no seu computador, depois spicyapi_task_create, que para para você confirmar o preço, e depois spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que faz um assistente de programação ler o esquema do modelo ao vivo em vez de adivinhar campos.

Revisar: material, contagem, tempo

Reproduza a imagem com som na velocidade normal e depois repita o contato em câmera lenta. As três falhas exigem correções diferentes:

• Material errado (um impacto metálico para uma xícara de cerâmica): substitua "object impact" por "ceramic cup on wood, soft contact".

• Eventos demais (vários impactos para um único contato): peça uma única colocação e remova palavras como rattling ou clattering. Mais passos não resolvem isso de forma confiável; simplifique o prompt ou mantenha o único bom contato e corte o resto na edição.
• Momento errado: meça o erro em mais de um evento. Um deslocamento constante é um pequeno ajuste no editor. Um erro que cresce ao longo do clipe é deriva, e mover a trilha inteira uma vez não resolve. Para um plano com um único contato, arrastar o início até o quadro do contato costuma ser mais rápido do que outra tentativa.

Cenas silenciosas ou delicadas (chuva, digitação, passos leves) são onde a trilha volta mais fina; nomeie o som como próximo e destacado, ou coloque por baixo uma ambiência de uma biblioteca de sons.

Clipes de diálogo e sincronização labial

Foley e Lip Sync gravam cada qual a sua própria trilha de áudio e substituem a do clipe, então uma cena com fala precisa de duas passadas. Execute o Foley primeiro na imagem muda e extraia a trilha de som como um único WAV mixado (a xícara, a roupa e o som do ambiente não são stems separados; FFmpeg stream selection):

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

Depois execute Lip Sync ou Talking Avatar para a voz e misture o WAV do Foley abaixo da fala:

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

Este comando preserva o vídeo de entrada inteiro; duration=first faz o áudio mixado seguir a primeira trilha de áudio de entrada. Adicione -shortest somente se quiser cortar a imagem quando esse áudio terminar. A trilha do Foley não repete sozinha: se o Lip Sync repete a imagem, coloque ou repita os efeitos você mesmo nos novos contatos, ou execute o Foley na imagem final já em loop.

Ajuste volume=0.35 pelo ouvido. Um contato de xícara que cai em uma consoante importante precisa de um nível mais baixo ou de outro ponto de corte, e um efeito que sozinho soa baixo pode se destacar em uma pausa. Faça um fade em um limite silencioso e mantenha o transitório de contato intacto; fazer fade através dele transforma um impacto em um baque abafado.

Custo

Uma execução básica mais dois prompts alternativos em um clipe de seis segundos custa $0.0216; dez clipes de seis segundos com uma tomada cada custam $0.072. Uma requisição concluída é cobrada seja qual for o resultado, então corrija o prompt antes de tentar de novo.

Para um primeiro resultado útil: termine a edição de imagem, nomeie o material e o contato reais, peça a duração exata do clipe e então corrija no prompt os erros de material e no editor os pequenos deslocamentos de tempo. Isso dá a você um próximo passo mais claro do que pedir de novo um "better cinematic sound".

FAQ

Posso manter o diálogo que já está no meu clipe? Não dentro da saída do Foley: o vídeo devolvido carrega apenas a trilha gerada. Misture o áudio original de volta no seu editor.

Ele faz música ou vozes? Não. Coloque música e fala em negative_prompt; mesmo assim pode aparecer um murmúrio parecido com voz, então ouça antes de entregar.