Flujo de trabajo de Foley API: añade y revisa el sonido de un vídeo

Para añadir efectos de sonido a un clip mudo ya terminado, envía su MP4 a Foley v1 junto con la duración del clip y una lista corta de lo que debería oírse. El precio es $0.0012 por segundo solicitado: un clip de seis segundos cuesta $0.0072 y la solicitud predeterminada de ocho segundos cuesta $0.0096. Recibes el mismo vídeo con la pista de sonido generada incorporada, no un archivo de audio aparte, y cualquier audio que trajera el clip de entrada se sustituye. Una tarea suele terminar en menos de un minuto.

Cuándo Foley es el paso adecuado

Úsalo cuando la imagen ya está definitiva y sin sonido: la salida de un modelo de vídeo que no tiene audio, un bucle de producto, un montaje preliminar que cuesta juzgar sin sonido. Produce efectos y ambiente (pasos, tazas, lluvia, tráfico, una cocina), no música, y el habla como mucho sale como un murmullo. Si tu modelo de vídeo puede generar sonido junto con la imagen, pídelo ahí; Foley es para clips que no puedes o no quieres regenerar. Para frases habladas usa Lip Sync o Talking Avatar; añade los efectos como se describe en la sección de diálogo más abajo.

Preparar el clip

Usa el plano final, no un montaje más largo con material sin usar. Para una escena de seis segundos en la que una adulta ficticia coloca una taza de cerámica sobre un escritorio de madera, incluye la aproximación de la mano, el contacto visible y un momento de reposo. El contacto es tu referencia de tiempo. Un corte a otro ángulo a mitad de escena añade un segundo límite de evento y dificulta más el diagnóstico de un mal resultado.

Usa un MP4 de hasta 90 MB: un enlace directo al archivo (no una página de compartir) o un archivo que subes desde tu ordenador (los archivos .mov se convierten a MP4 durante la subida; consulta Media). Conserva el original, porque el archivo devuelto contiene solo la pista nueva.

Pruébalo primero en el Playground

Abre Video Sound Effects en la pestaña Playground, en la vista Form, e inicia sesión con una cuenta con saldo para ejecutar.

1. Suelta tu MP4 en el campo Input video (o pega su enlace en Asset URL y pulsa Add URL).
2. Escribe en Prompt los sonidos que quieres, como una lista corta. Déjalo vacío para una pasada rápida.
3. Pon Duration en la duración de tu clip en segundos.
4. Abre Advanced parameters y escribe "music, speech" en Negative prompt.
5. Ejecuta el modelo y reproduce el clip devuelto con sonido.

Cambia una sola cosa por intento y corrige el prompt antes de reintentar, porque cada ejecución completada se factura.

Controles y qué dejar intacto

duration_seconds es lo que pagas, no la duración del clip. Un clip de seis segundos enviado con los ocho segundos predeterminados se factura por ocho y vuelve con seis segundos; un clip de diez segundos con duration_seconds: 6 vuelve recortado a seis. Ajústalo al clip. Un clip de más de 30 segundos tiene que cortarse en trozos de 30 segundos o menos en un cambio de escena, ejecutarse por separado y unir las pistas en tu editor; cada trozo se factura por sus propios segundos.

ignore_visual_semantics: true elige los sonidos del prompt en lugar de la imagen, mientras el movimiento sigue determinando el tiempo. Úsalo para un sonido que no está en pantalla, como un zumbido lejano tras un plano de ventana. No es una solución para el sonido de una taza que llega un poco tarde, y no cambia el precio. Sube un poco guidance_scale solo si el resultado ignora tu prompt. No hay seed.

Escribir el prompt

Enumera lo que hace ruido, no el ambiente: "espresso machine hiss, cups clinking, low café chatter" funciona; "cosy atmosphere" no. Nombra el material y el contacto ("ceramic cup on wood, soft contact") y describe solo lo que muestra la imagen. Pedir pasos en un plano donde la persona solo gira la cabeza produce un sonido plausible pero sin sincronizar. Omite el prompt para una pasada rápida; entonces el modelo empareja los sonidos con la acción.

Dos prompts de partida:

• Taza sobre un escritorio: "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".
• Tres pasos lentos, con ropa: "Three soft shoe steps on a wooden floor matching the visible foot contacts, a light jacket rustle, quiet indoor ambience." Si los pasos suenan como tacones, nombra la suela y la superficie; si solo suenan demasiado altos, baja la pista en el editor.

Las acciones rápidas y repetitivas son el caso difícil: un lápiz rascando a velocidad constante o páginas que giran deprisa rara vez caen trazo a trazo. Genera primero la base y luego coloca a mano una muestra limpia con el ritmo correcto, o deja que el ambiente lo cubra.

Y luego ejecútalo desde código

La misma solicitud en código. Instala el SDK de Python (pip install spicyapi), define SPICY_API_KEY en el entorno de tu servidor y ejecuta:

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

El enlace del resultado está firmado y dura unos 20 minutos, y el archivo se conserva 14 días, así que cópialo de inmediato a tu propio almacenamiento. Los presupuestos de precio, la espera, las descargas, los reintentos y los códigos de error están cubiertos en la guía de tasks y la referencia del SDK de Python.

O deja que un Agent lo ejecute

Cuando un asistente debe procesar los clips, las tres herramientas oficiales muestran el precio y te piden confirmación antes de una llamada de pago.

• CLI. Sube el clip, coloca en input.json la URI spicy:// devuelta y tu prompt, y luego:

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

Consulta la documentación de la CLI; npx @spicyapi/cli funciona sin instalar nada.

• Servidor MCP. Añade el servidor MCP a tu asistente y luego pregunta: "Add sound effects to this MP4 with Video Sound Effects: a ceramic cup placed on a wooden desk, no music or speech." Llama a spicyapi_upload_file para un archivo de tu ordenador, luego a spicyapi_task_create, que se detiene para que confirmes el precio, y luego a spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala el Agent Skill, que hace que un asistente de programación lea el esquema del modelo en vivo en lugar de adivinar campos.

Revisar: material, cantidad, tiempo

Reproduce la imagen con sonido a velocidad normal y luego repite el contacto despacio. Los tres fallos necesitan correcciones distintas:

• Material incorrecto (un golpe metálico para una taza de cerámica): sustituye "object impact" por "ceramic cup on wood, soft contact".
• Demasiados eventos (varios impactos para un solo contacto): pide una sola colocación y quita palabras como rattling o clattering. Más pasos no lo arreglan de forma fiable; simplifica el prompt o quédate con el único contacto bueno y recorta el resto.
• Momento incorrecto: mide el error en más de un evento. Un desfase constante es un pequeño ajuste en el editor. Un error que crece a lo largo del clip es deriva, y mover toda la pista una vez no lo arregla. Para un plano con un solo contacto, arrastrar el inicio hasta el frame del contacto suele ser más rápido que otro intento.

Las escenas tranquilas o delicadas (lluvia, tecleo, pasos suaves) son donde una pista vuelve más fina con más frecuencia; nombra el sonido como cercano y prominente, o coloca debajo un ambiente de una biblioteca de sonidos.

Clips de diálogo y sincronización labial

Foley y Lip Sync escriben cada uno su propia pista de audio y sustituyen la del clip, así que una escena con diálogo necesita dos pasadas. Ejecuta Foley primero sobre la imagen muda y extrae su pista de sonido como un único WAV mezclado (la taza, la ropa y el sonido de la habitación no son stems separados; FFmpeg stream selection):

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

Luego ejecuta Lip Sync o Talking Avatar para la voz y mezcla el WAV de Foley debajo del habla:

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 conserva el vídeo de entrada completo; duration=first hace que el audio mezclado siga la primera pista de audio de entrada. Añade -shortest solo si quieres cortar la imagen cuando termine ese audio. La pista de Foley no se repite sola: si Lip Sync repite la imagen, coloca o repite los efectos tú mismo en los nuevos contactos, o ejecuta Foley sobre la imagen final ya en bucle.

Ajusta volume=0.35 con el oído. Un contacto de taza que cae sobre una consonante clave necesita un nivel más bajo o un punto de corte distinto, y un efecto que suena callado por sí solo puede destacar en una pausa. Haz un fundido en un límite tranquilo y mantén intacto el transitorio del contacto; fundir a través de él convierte un impacto en un golpe sordo.

Coste

Una ejecución base más dos prompts alternativos sobre un clip de seis segundos cuesta $0.0216; diez clips de seis segundos con un pase cada uno cuestan $0.072. Una solicitud completada se factura sea cual sea el resultado, así que corrige el prompt antes de reintentar.

Para un primer resultado útil: termina el montaje de la imagen, nombra el material y el contacto reales, solicita la duración exacta del clip y luego corrige en el prompt los errores de material y en el editor los desfases de tiempo pequeños. Eso te da un siguiente paso más claro que volver a pedir "better cinematic sound".

FAQ

¿Puedo conservar el diálogo que ya hay en mi clip? No dentro de la salida de Foley: el vídeo devuelto solo lleva la pista generada. Mezcla el audio original de nuevo en tu editor.

¿Genera música o voces? No. Pon música y habla en negative_prompt; aun así puede aparecer un murmullo parecido a voz, así que escucha antes de entregar.