ミュージックビデオのエンドポイント
/v1/videos/music のすべてのエンドポイント——曲からミュージックビデオを作成、ポーリング、シーンの確認と編集、レンダリング、動画全体・1 シーン・ルックの参照シートのダウンロード、削除——のパラメータ、レスポンス、エラー。
ミュージックビデオ API は https://lovelyrouter.com/v1/videos/music 以下にあります。すべてのリクエストで API キーを Authorization: Bearer $LOVELY_API_KEY として送って認証します(認証)。リクエストは JSON または multipart、レスポンスは動画ファイル以外は JSON です。動画はプリペイド残高から課金されます。
全体の流れ——曲がどう動画になるか、ブリーフの書き方、所要時間と料金——はミュージックビデオのガイドから始めてください。
ミュージックビデオオブジェクト#
すべてのエンドポイントがこのオブジェクト、またはその一覧を返します。
属性
idstring一意の ID。mv_ に続く 24 文字。
objectstring常に music_video。
modelstringレンダリングに使うモデル:ltx-music-video または minimax-h3-music-video。
statusstringanalyzing、planning、ready(auto_render: false のときレンダリング待ち)、in_progress、completed、failed、cancelled のいずれか。
stepstringより細かいステップ:analyzing、planning、ready、rendering、stitching(シーンの結合)、succeeded、failed、cancelled。
planning_stepstring | nullplanning の間:casting(監督が歌い手とルックを決める)、profile(各ルックの参照シートを描く)、directing(ショットを書く)、frames(各シーンの最初のフレームを描く)。他のステータスでは null。
progressinteger0〜100:解析で 5、シーンの執筆で 15、レンダリングで 95、結合で 100 まで。
created_atintegerUnix 秒。
completed_atinteger | nullcompleted になった時刻。
expires_atinteger | nullファイルが削除される時刻。completed_at の 7 日後。
secondsnumber | null解析後は曲(またはスライス)の長さ、完成後は動画の長さ。
startnumber | null曲の中でスライスが始まる位置(秒)。曲全体を使うときは null。
endnumber | nullスライスが終わる位置(秒)——解析後、適用された値(曲の終わりを超える end は曲の終わりになります)。曲全体を使うときは null。
sizestringリクエストしたアスペクト比(16:9、9:16、1:1)。完成後は動画のピクセル数(例:1472x832)。
modestringimage(キャラクタープロフィールあり)または text。
briefobject送った story、style、character、locations(送らなかったものは null)。character_id があり character がないときは、character は保存したキャラクターの説明です。
character_idstring | null動画の作成に使った保存したキャラクター、または null。
director_modelstringシーンを書くチャットモデル。
image_modelstring | nullmode: "image" で参照シートと最初のフレームを描く画像モデル。
first_framesbooleanminimax-h3-music-video で最初のフレームも描くかどうか(作成リクエストの first_frames を参照)。
temponumber | null解析で得た曲のテンポ(1 分あたりの拍数)。
languagestring | null解析で歌詞を書き起こした言語。
characterstring | null監督がキャスティングした歌い手:顔、髪、体つき(服装は含まない)。mode: "text" とキャスティングが終わるまでは null。
looksarray歌い手のルック(衣装)、最大 4 つ。mode: "text" とキャスティングが終わるまでは空。
scenesarrayシーンごとに 1 項目、順番どおり。曲の解析が終わるまでは空。
errorobject | nullfailed と cancelled の動画のみ:code と message(課金されたかどうかも書かれています)。
urlstring | nullcompleted になった完成版の mp4。動画をダウンロードするを参照。
hold_usdnumber残高から保留されている金額:曲全体の料金。解析の終わりから動画の精算まで。それ以前は 0。
charge_usdnumber | null精算後の動画の料金。それ以前は null。
other_usdnumber監督のチャット呼び出しと、参照シートおよび最初のフレームの画像呼び出しにここまでかかった料金。それぞれの呼び出しとして課金され、charge_usd には含まれません。
powered_bystringLTX または MiniMax H3。
{
"id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
"object": "music_video",
"model": "ltx-music-video",
"status": "completed",
"step": "succeeded",
"planning_step": null,
"progress": 100,
"created_at": 1792915200,
"completed_at": 1792915330,
"expires_at": 1793520130,
"seconds": 16.13,
"start": null,
"end": null,
"size": "1472x832",
"mode": "image",
"brief": {
"story": "A night drive through a neon city that ends at the sea at dawn",
"style": "Cinematic 35 mm film, teal and orange, light rain",
"character": "A woman in her twenties with short black hair and a red leather jacket",
"locations": null
},
"character_id": null,
"director_model": "gemini-3.8-flash",
"image_model": "gpt-image-2",
"first_frames": false,
"tempo": 118,
"language": "en",
"character": "A woman in her twenties with short black hair in a blunt bob, dark brown eyes, light olive skin, a slim build and a small scar above her left eyebrow",
"looks": [
{
"id": 1,
"outfit": "A red leather jacket over a black T-shirt, dark jeans, black boots, silver hoop earrings",
"url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/looks/1/content"
}
],
"scenes": [
{
"index": 0,
"look": 1,
"start": 0,
"seconds": 5.375,
"lyrics": null,
"prompt": "A woman in her twenties with short black hair in a blunt bob, dark brown eyes, light olive skin, a slim build and a small scar above her left eyebrow, wearing a red leather jacket over a black T-shirt, dark jeans, black boots, silver hoop earrings. Style: Cinematic 35 mm film, teal and orange, light rain. She drives through the neon city, signs smearing across the wet windshield; the camera pushes in from the passenger seat.",
"status": "done",
"url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/0/content"
},
{
"index": 1,
"look": 1,
"start": 5.375,
"seconds": 5.042,
"lyrics": "we never looked back",
"prompt": "A woman in her twenties with short black hair in a blunt bob, … wearing a red leather jacket over a black T-shirt, … Style: Cinematic 35 mm film, teal and orange, light rain. Medium close-up: she sings \"we never looked back\" to the camera, hair whipping in the wind of the open window, handheld.",
"status": "done",
"url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/1/content"
},
{
"index": 2,
"look": 1,
"start": 10.417,
"seconds": 5.708,
"lyrics": null,
"prompt": "A woman in her twenties with short black hair in a blunt bob, … wearing a red leather jacket over a black T-shirt, … Style: Cinematic 35 mm film, teal and orange, light rain. She steps out of the car on an empty beach road as the sky turns pink; the camera tracks alongside her toward the sea.",
"status": "done",
"url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/2/content"
}
],
"error": null,
"url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/content",
"hold_usd": 0,
"charge_usd": 1.1288,
"other_usd": 0.1621,
"powered_by": "LTX"
}ミュージックビデオを作成する#
/v1/videos/music曲からミュージックビデオの作成を始め、すぐに 202 とミュージックビデオオブジェクトを返します。処理はバックグラウンドで進むので、ミュージックビデオを取得するで追ってください。multipart(song と character_image をファイルとして)か JSON(同じものを http(s) または data: の URL で)で送ります。歌い手は呼び出しと一緒に直接(character、character_image)送ることも、保存したキャラクター(character_id)から使うこともできます。どちらも使え、どちらも必須ではありません。デフォルトでは、まず歌い手をキャスティングして描きます(キャラクタープロフィール)。開始には最短の動画(15 秒)をまかなえる残高が必要で、曲の長さがわかった時点で曲全体の料金が保留されます。
ボディパラメータ
modelstring必須ltx-music-video または minimax-h3-music-video(モデルを参照)。
songfile or string必須曲:MP3、WAV、FLAC、OGG、M4A、5 秒から 6 分、最大 60 MB。ファイル、または http(s) / data: の URL(song_url でも可)。
startnumber曲の一部だけを使います:スライスが始まる位置(秒、デフォルト 0)。解析、シーン、歌詞、サウンドトラックはすべてスライスに従い、料金はスライスの長さに対してかかります。曲の一部を使うを参照。
endnumberスライスが終わる位置(秒、デフォルト:曲の終わり)。end − start は 5 秒以上 6 分以下でなければなりません。
consentboolean必須true:モデルの規約——LTX 規約または MiniMax H3 規約(その地域条項を含む)——とその順守の責任を受け入れ、ブリーフや画像に登場する識別可能な人物が全員 18 歳以上で、この肖像の使用に同意していることを確認します。
storystring曲を通して起こること。他のブリーフ項目と同じく最大 4,000 文字。
stylestring見た目:フィルムかアニメか、色、光、レンズ。各シーンのプロンプトに加えられます。
characterstring歌い手(顔、髪、体つき、メインのルックの服装)。キャスティングは細部をすべて残し、足りない部分を補います。mode: "text" では各シーンのプロンプトにそのまま加えられます。
locationsstringストーリーが通る場所。
lyricsstring書かれたとおりの歌詞。正しい表記のため。任意:歌詞はどのみち書き起こされます。
languagestring書き起こしに使う曲の言語。例:en、zh、ja。デフォルト:自動判定。
sizestringデフォルト 16:916:9、9:16、1:1:ltx-music-video では 1472×832、832×1472、1152×1152、minimax-h3-music-video では 1344×768、768×1344、1024×1024。
modestringデフォルト imageimage:キャラクタープロフィール——監督が歌い手と最大 4 つのルックをキャスティングし、image_model がルックごとに参照シートを描き、各シーンはそのルックのシートから描いた最初のフレームから始まります(minimax-h3-music-video では各シーンをシートそのものから撮影します。first_frames を参照)。text:画像なし、各シーンをプロンプトだけから。キャラクタープロフィールが必要な minimax-h3-music-video では使えません。
image_modelstringデフォルト gpt-image-2mode: "image" のみ。キーで使える画像モデルのうち、参照画像(編集)に対応したもの(例:gpt-image-2)。生成だけのモデルは 400 で拒否されます。通常の画像ジョブとして課金され、目安はルックごとに 1 枚とシーンごとに 1 枚です。
first_framesbooleanデフォルト falseminimax-h3-music-video のみ(他のモデルは mode: "image" で常に最初のフレームを描きます)。このモデルは最初のフレームなしで、ルックのシートから歌い手を撮影します。true にすると各シーンの冒頭のフレームも描き、シートと一緒にモデルに渡します。各シーンがどこで、どう始まるかをより細かく決められる代わりに、シーンごとに画像が 1 枚増え、レンダリングも遅くなります。その場合、動画は 1 秒あたり $0.13 ではなく $0.2 で課金されます。
character_imagefile or stringmode: "image" のみ。歌い手の画像で、ルック 1 のシートの元になります:PNG、JPEG、WebP、最大 20 MB、ファイルまたは URL(character_image_url でも可)。
character_idstringmode: "image" のみ。あなたのアカウントの保存したキャラクター:そのシートが character_image と同じように使われ、character を送らなければその説明が character として使われます。character_image とは併用できません。
director_modelstringデフォルト gemini-3.8-flashシーンを書くチャットモデル。キーで使える任意のチャットモデル。通常のチャット呼び出しとして課金。
scene_secondsnumberデフォルト 5目標とするシーンの長さ、2〜10 秒。カットはビートに合わせるので、シーンの長さはこの前後で変わります。
seedinteger再現可能なシーン(0〜2147483647)。デフォルト:ランダム。
クエリパラメータ
waitinteger0〜300。動画に変化(ステップの切り替え、シーンの完成)があるか時間切れになるまでリクエストを保持します。その時点で終わっていれば 200。
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 that ends at the sea at dawn" \
-F style="Cinematic 35 mm film, teal and orange, light rain" \
-F character="A woman in her twenties with short black hair and a red leather jacket" \
-F start=42.5 -F end=102.5 \
-F consent=true
# 直接送るキャラクターのテキストと画像の代わりに、保存したキャラクターで:
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 consent=true{
"id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
"object": "music_video",
"model": "ltx-music-video",
"status": "analyzing",
"step": "analyzing",
"planning_step": null,
"progress": 2,
"seconds": null,
"size": "16:9",
"mode": "image",
"character": null,
"looks": [],
"scenes": [],
"error": null,
"url": null,
"hold_usd": 0,
"charge_usd": null,
"other_usd": 0,
"powered_by": "LTX"
}ミュージックビデオを取得する#
/v1/videos/music/{id}ミュージックビデオオブジェクトを返します。status が completed、failed、cancelled になるまでポーリングしてください。
クエリパラメータ
waitinteger0〜300。ロングポーリング:ステップが変わるか次のシーンが完成した時点で、そうでなければ時間切れで返ります。ready の動画はすぐに返ります。
curl "https://lovelyrouter.com/v1/videos/music/MUSIC_ID?wait=120" \
-H "Authorization: Bearer $LOVELY_API_KEY"ミュージックビデオを一覧表示する#
/v1/videos/musicあなたのミュージックビデオ。新しい順。
クエリパラメータ
limitintegerデフォルト 201〜100。
afterstringミュージックビデオの ID:それより前に作られたものを一覧表示します(次のページ)。
curl "https://lovelyrouter.com/v1/videos/music?limit=10" \
-H "Authorization: Bearer $LOVELY_API_KEY"{
"object": "list",
"data": [{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video", "status": "completed" }],
"first_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
"last_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
"has_more": false
}シーンを編集する#
/v1/videos/music/{id}動画が ready(auto_render: false で作成)の間、シーンのプロンプトを書き直します。送ったプロンプトはシーンの prompt をそのまま置き換えます——キャラクター、ルック、style は改めて加えられないので、プロンプトに残してください。mode: "image" では最初のフレームはもう描かれています。新しいプロンプトはシーンの動きを変えますが、最初のフレームは変えません。ミュージックビデオオブジェクトを返します。他のステータスでは 409。
ボディパラメータ
scenesarray必須変更するシーン。
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 a red leather jacket. She sings \"we never looked back\" on an empty pier at dawn, the camera orbiting her."}]}'ミュージックビデオをレンダリングする#
/v1/videos/music/{id}/renderready の動画のレンダリングを始めます。in_progress になったミュージックビデオオブジェクトを返します。他のステータスでは 409。1 日以内にレンダリングされなかったプランは、料金なしでキャンセルされます。
curl -X POST https://lovelyrouter.com/v1/videos/music/MUSIC_ID/render \
-H "Authorization: Bearer $LOVELY_API_KEY"動画をダウンロードする#
/v1/videos/music/{id}/content完成した mp4。サウンドトラックはその曲です。Range リクエストに対応しているので、プレーヤーでシークできます。7 日間保存。completed になる前は 409、削除または期限切れの後は 410。
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/content \
-H "Authorization: Bearer $LOVELY_API_KEY" -o music-video.mp4シーンをダウンロードする#
/v1/videos/music/{id}/scenes/{n}/contentレンダリング済みの 1 シーンの mp4(その部分の曲付き)。動画全体の完成を待たず、そのシーンが done になればすぐに取得できます。n はシーンの index。レンダリング前は 409。
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/scenes/0/content \
-H "Authorization: Bearer $LOVELY_API_KEY" -o scene-0.mp4ルックのシートをダウンロードする#
/v1/videos/music/{id}/looks/{n}/contentルックのターンアラウンド参照シート(正面、斜め、横、背面)。描き終わればすぐ、プランニング中、どのシーンもレンダリングされる前に取得できます。n はルックの id(1 から)。まだ描かれていないときと mode: "text" では 404。
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/looks/1/content \
-H "Authorization: Bearer $LOVELY_API_KEY" -o look-1.png削除#
/v1/videos/music/{id}終わった動画(completed、failed、cancelled):ファイルを削除し、一覧から外します。ready で待っているプラン(auto_render: false):破棄します。料金はかかりません。分析やレンダリングを始めた動画は止められません:409 を返します。終わるのを待ってから削除してください。
curl -X DELETE https://lovelyrouter.com/v1/videos/music/MUSIC_ID \
-H "Authorization: Bearer $LOVELY_API_KEY"{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video.deleted", "deleted": true }エラー#
エラーは標準のエラーボディを使います。開始後に失敗した動画は HTTP エラーではありません:status が failed になり、error に理由が入ります。
| ステータス | type / code | 理由 |
|---|---|---|
400 | consent_required | consent が true ではありません。 |
400 | invalid_request_error | 曲や画像がない、読めない、ファイルが大きすぎる、フィールドが範囲外、5 秒より短いか 6 分より長いスライス、mode: "image" なしの character_image、character_id または first_frames、minimax-h3-music-video での mode: "text"、character_image と character_id の両方、またはキーで使えない director_model / image_model。 |
401 | authentication_error | API キーがないか無効です。 |
402 | insufficient_quota | 残高、またはキーの利用上限が、最短の動画に足りません。 |
404 | not_found_error | 不明なモデルまたはミュージックビデオ、ミュージックビデオを作らないモデル、あなたの保存したキャラクターではない character_id、またはシートがまだ描かれていないルック。 |
409 | invalid_request_error | ready でない動画の編集やレンダリング、またはまだレンダリングされていないファイルのダウンロード。 |
410 | not_found_error | 動画は削除されたか期限切れです。 |
429 | rate_limit_exceeded | アカウントでミュージックビデオがすでに 2 本進行中、またはキーのレート制限。 |
失敗した動画には次のいずれかの error.code が付きます:invalid_request_error(曲を使えなかった。5 秒未満や 6 分超、または曲の終わりを超える start など)、insufficient_quota(残高が曲全体に足りなかった)、capacity_exhausted(GPU が空かなかった)、api_error(当社側の問題)、expired(ready のプランが 1 日待った)、cancelled(ready で破棄したプラン)。どの場合も動画の料金はかかりません。