ミュージックビデオ

POST /v1/videos/music は曲をミュージックビデオにします。音声と短いブリーフ（ストーリー、見た目、登場人物）を送ると、曲と同じ長さの mp4 が返ってきます。サウンドトラックはその曲です。コードなしで Playground から試せます。すべてのフィールドとレスポンスは API リファレンスにあります。

仕組み#

1. 解析。 曲のビートを見つけ、ビートで終わるシーンに分けます。各シーンは約 scene_seconds（デフォルト 5 秒）で、長さは曲全体で均等に調整されるため最後のシーンが極端に短くなることはなく、動画は曲の終わりちょうどで終わります。歌詞はシーンごとに書き起こします。
2. キャスティング。 あなたが選んだチャットモデル——監督——がブリーフと歌詞を読み、歌い手を一度だけ決めます：キャラクターの描写（顔、髪、体つき。服装は含まない）と、ストーリーに必要なルック（衣装）、最大 4 つ。
3. キャラクタープロフィール。 画像モデルがルックごとにターンアラウンドの参照シートを描きます：歌い手の正面、斜め、横、背面。
4. 演出。 監督が、ブリーフ、そのシーンの歌詞、前後のシーンから、シーンごとに 1 ショットを書き——画面に何があり、何が起こり、カメラがどう動き、光はどうか——そのシーンで歌い手が着るルックを選びます。歌い手が映るときは、何を歌うかもショットに書きます。
5. 最初のフレーム。 各シーンの最初のフレームはそのルックのシートから描かれるので、どのシーンも同じ人物から始まります。minimax-h3-music-video は指定しない限り（first_frames）この手順を飛ばし、シートそのものから歌い手を撮影します。
6. レンダリング。 各シーンは最初のフレーム（またはそのルックのシート）とプロンプトからレンダリングされ、その部分の曲が映像を動かします。歌い手の口は歌詞に合い、動きやカットは音楽に合います。
7. 結合。 シーンは順番に元の曲の上でつながれます。音は送った曲そのままです。

手順 2、3、5 がキャラクタープロフィールで、デフォルトで有効です。mode: "text" ではこれらを省き、各シーンをプロンプトだけからレンダリングします。進み具合はミュージックビデオオブジェクトをポーリングして追えます。status、パーセントの progress、ルックとそのシート、そしてシーンごとの歌詞、プロンプト、レンダリング後はそのシーン自体のクリップ。

モデル#

どちらも 5 秒から 6 分の曲に対応し、当社の GPU 上で creative-hosted チャネルグループとして動作します。すべてのリクエストで consent: true を設定し、モデルの規約とその順守の責任を受け入れます：ltx-music-video は LTX 規約、minimax-h3-music-video は MiniMax H3 規約——EU・英国・韓国・米国でモデルやその出力を利用しないことを含みます（地域）。

ミュージックビデオを作る#

曲はファイル song（multipart）として送るか、song または song_url に http(s) か data: の URL を指定します（JSON）。MP3、WAV、FLAC、OGG、M4A、最大 60 MB。

curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video \
  -F song=@song.mp3 \
  -F story="A night drive through a neon city; she leaves the old town behind and reaches the sea at dawn" \
  -F style="Cinematic 35 mm film, teal and orange, light rain, shallow depth of field" \
  -F character="A woman in her twenties with short black hair, a red leather jacket and silver hoop earrings" \
  -F size=16:9 \
  -F consent=true

リクエストはすぐに 202 とミュージックビデオオブジェクトを返します。接続を切ってもジョブは続きます。完成した mp4 は 7 日間保存されます。

ブリーフを書く#

どのフィールドも任意で、最大 4,000 文字です。ブリーフがまったくなければ、監督が歌詞からストーリー、歌い手、見た目を考えます。

language は曲の言語を書き起こしに伝えます（en、zh、ja など）。指定しなければ自動で判定します。

曲の一部を使う#

start と end（曲の先頭からの秒数）を送ると、曲の一部——サビ、最初の 1 分——だけの動画を作れます。曲は何よりも先に切り出されるので、完成した動画のビート、シーン、歌詞、サウンドトラックはスライスのものになり、料金は曲ではなくスライスの長さに対してかかります。

• start だけなら曲の終わりまで、end だけなら 0 から始まります。
• スライスの長さ（end − start）は 5 秒から 6 分です。曲自体はそれより長くても構いません。
• 曲の終わりを超える end は曲の終わりになります。曲の終わりを超える start は解析の後に失敗し、料金はかかりません。
• オブジェクトの start と end には適用されたスライスが表示されます（曲全体なら null）。シーンの時刻（scenes[n].start）はスライスの始まりから数えます。

curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 \
  -F start=42.5 -F end=102.5 \
  -F consent=true

Playground には、プレビュー付きのスライサーがあります。

キャラクタープロフィール#

デフォルトは mode: "image" です。シーンを書く前に歌い手をキャスティングして描くので、すべてのシーンを同じ人物が歌います。

• キャスティング。 監督がキャラクター（オブジェクトの character）とルック（looks）を答えます。ルック 1 がメインの衣装で、ストーリーが着替えを求める場合にだけ別のルックを足します——最大 4 つ、たいていは 1 つか 2 つ。
• シート。 image_model（デフォルト gpt-image-2。キーで使える任意の画像モデル）がルックごとにターンアラウンドの参照シートを描きます：無地の背景で正面、斜め、横、背面。character_image——歌い手の画像、PNG、JPEG、WebP、最大 20 MB——を送るとそこから、または保存したキャラクターのシート（character_id、下記）から、ルック 1 が作られます。他のルックはすべてルック 1 のシートの編集なので、顔が引き継がれます。各シートは描き終わるとすぐ looks[n].url で取得できます。
• ルックごとのショット。 監督はすべてのショットをいずれかのルックで書き（scenes[n].look）、ストーリーのひとまとまりの間は同じルックを保ちます。シーンのプロンプトはキャラクターとそのルックの衣装から始まります。
• 最初のフレーム。 各シーンの最初のフレームはそのルックのシートから描かれ、シーンはそのフレームからレンダリングされ、曲が口の動きを決めます。
• minimax-h3-music-video では、各シーンを最初のフレームなしでそのルックのシートそのものから撮影し、プロンプトには服装を書きません。服装はシートが伝えます。first_frames: true を送ると各シーンの冒頭のフレームも描いてシートと一緒にモデルに渡すので、場所や構図をより細かく決められます（シーンごとに画像が 1 枚増え、レンダリングは遅くなります）。

キャラクタープロフィールには、参照画像（編集）に対応した画像モデル（たとえば gpt-image-2）が必要です。すべてのルックと最初のフレームをシートから描くので、顔がそれぞれに引き継がれます。mode: "image" で生成だけのモデルを指定すると 400 で拒否されます。参照画像に対応したモデルを使うか、mode: "text" にしてください。

シートと最初のフレームは、あなたのキーでの通常の画像ジョブで、その画像モデルの料金で課金され、ログに表示されます。通常はルックごとに 1 枚とシーンごとに 1 枚です（オブジェクトの other_usd がその合計です）。

直接か保存済みか#

歌い手は呼び出しごとに送ることも、一度保存して ID を渡すこともできます——どちらも同じように使えます：

• 1 回限り： character（テキスト）と／または character_image（画像）。上記のとおりです。
• 保存済み： character_id = あなたのアカウントの保存したキャラクター（POST /v1/characters：名前、説明、ターンアラウンドシート）。そのシートが character_image として、自分でテキストを送らなければその説明が character として使われます。オブジェクトの character_id に、どれを使ったかが表示されます。

character_id には mode: "image" が必要で、character_image とは併用できません。

curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2 \
  -F story="She drives through the night to the sea" \
  -F consent=true

mode: "text" はプロフィールを省きます：キャスティングも画像もなく、各シーンはあなたの character のテキストを含むプロンプトだけからレンダリングされます。速くて安価ですが、シーンごとに歌い手が変わることがあります。

監督#

director_model は歌い手をキャスティングしショットを書くチャットモデルを選びます。キーで使える任意のチャットモデルで、デフォルトは gemini-3.8-flash。1 回の呼び出しで 8 ショットを書き、その呼び出しは他のチャット呼び出しと同じくあなたのキーを通り、そのモデルの料金で課金されます。速くて安いモデルで十分です。キャスティングやショットに失敗した場合、何もレンダリングされる前に動画は止まり、動画の料金はかかりません。

指示はこれがすべてです（原文は英語）。キャスティング：

You cast a music video before it is shot. From the brief and the song, define the singer once, so that a reference photo of them can be made and every scene shows the same person.
- The character: face, age, skin, hair, eyes, build and distinctive features — no clothes, no setting, no action. Keep every detail the brief gives, word for word, and add what is missing.
- The looks: the outfits the singer wears. Look 1 is the main one (from the brief, if it names clothes). Add another look only where the story clearly calls for a change of clothes; at most 4 looks, usually one or two. Write each outfit as "Upper: …" then "Lower: …". Upper is only what a chest-up close-up shows — top, neckline, jacket, jewellery, anything in the hair — and never a length, hem or anything below the waist (a gown is "a crimson satin bodice with thin straps", not "a floor-length gown"). Lower is the rest: trousers, skirt or the gown's length and slit, shoes. Garments, colours, materials; no setting.
- English, concrete words. Never write about yourself or the task.

ショット：

You direct a music video. The song is cut into scenes that end on its beats; for every scene you write the prompt a text-to-video model renders while that part of the song plays. The model hears the music and moves the picture to it — lips, dancing, cuts — so describe the picture only.
- The brief comes first: its story, style, people and places. The people look the same in every scene; don't describe their faces, hair or clothes — that is added to every prompt for you from the character profile.
- Every scene with lyrics is a performance shot: the singer is on screen, mouth visible, and sings that scene's words — write "sings" and the words in double quotes. Keep the singer between a close-up and a medium shot for the whole shot: a gentle pull back or push within that range is fine, a wide shot or a big pull away is not (a face that gets small comes out distorted). Scenes without lyrics are story or atmosphere shots; nobody sings, and wider framing is fine, with people small or turned away.
- Make the camera work varied, like a real music video: change the angle and the move from scene to scene — eye level, low angle, high angle, profile, three-quarter, over-the-shoulder, a lateral tracking shot, an orbit, a handheld follow, a slow crane at eye level, a gentle pull back, a push in now and then. Never the same move two scenes in a row, and not a push in every time.
- In a performance shot the singer's face stays in frame from the first frame to the last: the camera never tilts down to the ground, and the prompt never mentions the ground, puddles, reflections on the pavement, legs, feet or shoes (the video model turns its eye to whatever is named). Describe the light on her, the background behind her and her expression instead.
- Follow the song: quiet parts slower and closer, the chorus with more movement and energy; follow the story from scene to scene.
- Every prompt: what is on screen, what happens (verbs), what the camera does, the light and colour.
- Present tense, concrete words, English; quoted lyrics in the song's own language. At most 70 words a prompt. Never write about yourself, the task or these rules.

レンダリング前にシーンを確認する#

"auto_render": false にすると、すべてのシーンにプロンプトと最初のフレームができた時点で、何もレンダリングせずにステータス ready で止まります。シートとフレームを見て、好きなシーンを書き直してから、レンダリングを始めます：

# シーン 3 を書き直す（インデックスは 0 から）
curl -X PATCH https://lovelyrouter.com/v1/videos/music/MUSIC_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" -H "content-type: application/json" \
  -d '{"scenes": [{"index": 2, "prompt": "A woman in her twenties with short black hair and silver hoop earrings, wearing a red leather jacket over a black T-shirt. Style: Cinematic 35 mm film. She sings \"we never looked back\" into the wind on an empty pier, the camera orbiting her at dawn."}]}'

# レンダリング
curl -X POST https://lovelyrouter.com/v1/videos/music/MUSIC_ID/render -H "Authorization: Bearer $LOVELY_API_KEY"

シーンの prompt は、そのシーンが実際にレンダリングする内容そのものです：キャラクターとそのルックの衣装（mode: "text" ではあなたの character のテキスト）、style、続いてショット。送ったプロンプトはそのまま置き換わるので、人物の描写を残してください。ready の時点で最初のフレームはもうできています。プロンプトを書き直すとシーンの動きは変わりますが、最初のフレームは変わりません。1 日以内にレンダリングされなかったプランはキャンセルされ、料金はかかりません。

所要時間#

• 解析：1 分以内。
• キャラクタープロフィールと最初のフレーム：画像モデルによりますが、たいてい数分。最初のフレームは並行して描かれます。mode: "text" ではこの手順はありません。
• シーン：GPU が温まっていれば順番にレンダリングします——ltx-music-video は 1 シーン約 20〜25 秒、minimax-h3-music-video は約 45 秒。3 分の曲を 5 秒のシーンで（約 36 シーン）作ると、ltx-music-video でおおよそ 12〜15 分、minimax-h3-music-video で 25〜30 分です。
• コールドスタート：動いている GPU がなければ約 1 分半を足してください。

各シーンのクリップはレンダリングされた時点で使えます（scenes[n].url）。動画ができあがっていく様子を見せられます。

料金#

曲の秒数に対して支払います。1 本あたり最低 15 秒分です：

監督の呼び出しとキャラクタープロフィールの画像（通常はルックごとに 1 枚とシーンごとに 1 枚）は、それぞれのチャット呼び出し・画像呼び出しとして、そのモデルの料金で別に課金されます（オブジェクトの other_usd がその合計です）。

• 開始するには、15 秒の最低料金をまかなえる残高が必要です。
• 解析の後、曲の長さがわかった時点で、曲全体の料金が残高から保留されます（hold_usd）。残高が足りなければ動画は insufficient_quota で失敗し、料金はかかりません。
• 完成時、動画の秒数が 1 回の呼び出しとしてログに課金され（charge_usd）、保留は解除されます。
• 開始後はキャンセルできません：送った動画は最後まで進みます。先に確認したい場合は auto_render: false でプランを確認してください。ready のプランは DELETE で無料で破棄できます（すでに行われた監督の呼び出しと画像は課金されます）。
• 当社側の原因で失敗した場合、動画の料金はかかりません。

制限#

• 1 アカウントで同時に進行できるミュージックビデオは 2 本まで。3 本目は 1 本が終わるまで 429 で拒否されます。
• 曲は 5 秒から 6 分、最大 60 MB。それより長い曲は解析の後に失敗し、料金はかかりません——または曲のスライス（5 秒から 6 分）を送ってください。
• scene_seconds は 2〜10。カットはビートに合わせるので、シーンの長さは選んだ値の前後で変わります。