Foley API 워크플로: 영상에 소리를 넣고 확인하기

이미 완성된 무음 클립에 효과음을 넣으려면 클립 길이와 무엇이 들려야 하는지 짧은 목록을 함께 묶어 MP4를 Foley v1에 보내면 됩니다. 가격은 요청한 초당 $0.0012입니다. 6초짜리 클립은 $0.0072, 기본값인 8초 요청은 $0.0096입니다. 돌아오는 것은 별도의 오디오 파일이 아니라 생성된 사운드트랙이 붙은 동일한 영상이며, 입력 클립에 있던 오디오는 모두 교체됩니다. 작업은 보통 1분 안에 끝납니다.

Foley가 알맞은 단계인 경우

이미지가 이미 확정됐고 소리가 없을 때 사용합니다. 오디오가 없는 영상 모델의 출력, 제품 루프, 소리 없이 판단하기 어려운 러프 컷이 그렇습니다. 만들어지는 것은 효과음과 앰비언스(발걸음, 컵, 비, 교통, 주방)이며 음악이 아닙니다. 말은 아무리 잘해도 중얼거림 정도로만 나옵니다. 영상 모델이 이미지와 함께 소리를 생성할 수 있다면 그쪽에서 요청하세요. Foley는 다시 생성할 수 없거나 다시 만들고 싶지 않은 클립을 위한 것입니다. 대사에는 Lip Sync 또는 Talking Avatar를 사용하고, 효과음은 아래 대화 섹션에서 설명한 방법으로 더합니다.

클립 준비하기

사용하지 않은 소재가 섞인 긴 편집본이 아니라 최종 컷을 사용하세요. 가상의 성인이 나무 책상에 도자기 컵을 내려놓는 6초 장면이라면 손이 다가오는 과정, 보이는 접촉, 잠깐의 정지를 담으세요. 그 접촉이 타이밍 기준점입니다. 중간에 다른 앵글로 자르면 이벤트 경계가 하나 더 생겨 나쁜 결과를 진단하기 어려워집니다.

90 MB 이하의 MP4를 준비하세요. 파일로 직접 가는 링크(공유 페이지가 아니어야 함)나 컴퓨터에서 올리는 파일을 쓰면 됩니다(.mov 파일은 업로드 중 MP4로 변환됩니다. Media 참고). 반환되는 파일에는 새 트랙만 들어 있으므로 원본은 보관하세요.

먼저 Playground에서 시도하기

Video Sound Effects를 Playground 탭의 Form 뷰에서 열고, 잔액이 있는 계정으로 로그인해 실행하세요.

1. Input video 필드에 MP4를 끌어다 놓습니다(또는 Asset URL에 링크를 붙이고 Add URL을 누릅니다).

1. Prompt에 원하는 소리를 짧은 목록으로 적습니다. 대충 한 번 돌려보려면 비워 두세요.
2. Duration을 클립 길이(초)로 설정합니다.
3. Advanced parameters를 열고 Negative prompt에 "music, speech"를 넣습니다.
4. 모델을 실행하고 반환된 클립을 소리와 함께 재생합니다.

시도할 때마다 한 가지만 바꾸고, 다시 실행하기 전에 프롬프트를 고치세요. 완료된 실행은 모두 과금됩니다.

파라미터와 그대로 둘 것

| 필드 | 허용 입력 | 시작값 |

| --- | --- | --- | | video_url (Input video) | MP4, 90 MB 이하 | 최종 클립의 직접 URL | | 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입니다. 6초 클립을 기본값인 8초로 보내면 8초로 과금되고 돌아올 때는 6초 분량입니다. 10초 클립에 duration_seconds: 6을 지정하면 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일간 보관되므로 곧바로 자체 저장소로 복사하세요. 견적, 대기, 다운로드, 재시도, 오류 코드는 tasks 가이드와 Python SDK 레퍼런스에서 다룹니다.

Agent에게 맡기기

어시스턴트가 클립을 처리하게 하려면 공식 도구 세 가지 모두 가격이 표시되고 유료 호출 전에 확인을 요청합니다.

• CLI. 클립을 올려서 반환된 spicy:// URI와 프롬프트를 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로 추출하세요(컵, 옷, 실내 소리가 별도의 stem은 아닙니다. FFmpeg stream selection 참고).

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

그런 다음 Lip Sync 또는 Talking Avatar로 음성을 만들고 Foley WAV를 대사 아래에 믹싱하세요.

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는 귀로 조절하세요. 중요한 자음에 걸리는 컵 접촉음은 레벨을 낮추거나 다른 편집 지점이 필요하고, 혼자서는 조용해 보이는 효과음도 침묵 구간에서는 두드러질 수 있습니다. 조용한 경계에서 페이드시키면서 접촉 트랜지언트는 온전히 유지하세요. 그 구간을 넘어 페이드하면 타격음이 뭉친 둔탁한 소리가 됩니다.

비용

6초 클립에서 기준 실행 한 번에 대안 프롬프트 두 개를 더하면 $0.0216, 6초 클립을 한 번씩 열 번 만들면 $0.072입니다. 완료된 요청은 결과가 어떤 소리든 과금되므로 다시 실행하기 전에 프롬프트를 고치세요.

처음 쓸 만한 결과를 얻으려면: 이미지 편집을 마무리하고, 실제 재질과 접촉을 밝히고, 클립과 정확히 같은 길이를 요청한 다음, 재질 오류는 프롬프트에서, 작은 타이밍 어긋남은 편집기에서 고치세요. 그러면 "better cinematic sound"를 다시 요청하는 것보다 다음 단계가 분명해집니다.

FAQ

제 클립에 이미 있는 대사를 유지할 수 있나요? Foley 출력 안에서는 불가능합니다. 반환되는 영상에는 생성된 트랙만 들어 있습니다. 원본 오디오는 편집기에서 다시 믹싱하세요.

음악이나 목소리를 만드나요? 아니요. 음악과 말은 negative_prompt에 넣으세요. 그래도 말처럼 들리는 중얼거림이 나타날 수 있으니 납품 전에 들어 보세요.