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. モデルを実行し、返されたクリップを音つきで再生します。

試すたびに変更点は1つだけにし、再実行の前にプロンプトを直してください。完了した実行はすべて課金されます。

パラメータと触ってはいけない設定

| フィールド | 指定できる値 | 開始値 |

| --- | --- | --- | | 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.」歩音がヒールのように聞こえる場合は、靴底と床面を明記してください。音が大きいだけなら、編集ソフトでトラックを下げます。

速く繰り返す動作は難しいケースです。一定速度で引っ掻く鉛筆や高速でめくるページは、1画ずつ合うことがまれです。まず土台を生成し、正しいリズムできれいなサンプルを手作業で配置するか、環境音で覆い隠してください。

続いてコードから実行する

同じリクエストをコードで書くと次のようになります。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」に置き換えます。

• 事象が多すぎる（1回の接触で複数の衝突）：一回だけの設置を要求し、rattlingやclatteringといった語を削除します。ステップを増やしても確実に直るわけではありません。プロンプトを簡略化するか、使える接触を1つだけ残して、ほかを編集で消してください。
• タイミングの誤り：複数の事象で誤差を測ってください。一定のオフセットは編集ソフトでの微調整で直せます。クリップとともに増えていく誤りはドリフトで、トラック全体を一度動かしても直りません。接触が1回だけのカットなら、音の開始位置を接触フレームまでドラッグするほうが、次の実行より早いことがほとんどです。

静かで細かな場面（雨、キーボード入力、やわらかな足音）は、トラックが薄くなりがちな場所です。近い音として前景で指定するか、下にライブラリの環境音を敷いてください。

対話とリップシンクのクリップ

FoleyもLip Syncもそれぞれ独自の音声トラックを書き、クリップの音声を置き換えるため、音声がある場面では二回の工程が必要です。まず無音の映像にFoleyを実行し、生成されたサウンドトラックを1つのmix済み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を音声の下にmixします。

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により、mixされた音声は1つ目の入力音声トラックに追従します。映像もその音声の終了で切り詰めたい場合にのみ-shortestを追加してください。Foleyのトラックは自動ではループしません。Lip Syncが映像を繰り返す場合は、新しい接触位置に合わせて効果音を手動で配置するかくり返すか、最終のループ済み映像にFoleyを実行してください。

volume=0.35は耳で調整してください。重要な子音の位置に落ちるカップの接触音は、音量を下げるか、編集位置を変える必要があります。単体では小さく聞こえる効果音でも、無音の瞬間に目立つことがあります。静かな境界でフェードさせ、接触のトランジェントは壊さないでください。その上を横切ってフェードさせると、衝撃音がこもった打撃に変わります。

コスト

6秒のクリップで基準となる一回実行に代替プロンプトを二つ加えると$0.0216、6秒クリップを1 takeずつ10本作ると$0.072です。完了したリクエストは結果の聞こえ方にかかわらず課金されるため、再実行の前にプロンプトを直してください。

最初に実用的な結果を得るには、映像の編集を仕上げ、本物の材質と接触を指定し、クリップ長と同じ秒数を要求し、材質の誤りはプロンプトで、わずかなタイミングのずれは編集ソフトで直します。そのほうが「better cinematic sound」ともう一度頼むより、次の手順が明確になります。

FAQ

すでにクリップにある会話は残せますか？ Foleyの出力内ではできません。返される動画には生成されたトラックだけが含まれます。元の音声は編集ソフトでmixし直してください。

音楽や声は作られますか？ いいえ。音楽と音声はnegative_promptに入れてください。声を思わせるような呟きが現れることがあるため、納品前に必ず試聴してください。