Lovely Routerドキュメント
キーを取得
API リファレンス

ミュージックビデオのエンドポイント

/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。

statusstring

analyzing、planning、ready(auto_render: false のときレンダリング待ち)、in_progress、completed、failed、cancelled のいずれか。

stepstring

より細かいステップ:analyzing、planning、ready、rendering、stitching(シーンの結合)、succeeded、failed、cancelled。

planning_stepstring | null

planning の間:casting(監督が歌い手とルックを決める)、profile(各ルックの参照シートを描く)、directing(ショットを書く)、frames(各シーンの最初のフレームを描く)。他のステータスでは null。

progressinteger

0〜100:解析で 5、シーンの執筆で 15、レンダリングで 95、結合で 100 まで。

created_atinteger

Unix 秒。

completed_atinteger | null

completed になった時刻。

expires_atinteger | null

ファイルが削除される時刻。completed_at の 7 日後。

secondsnumber | null

解析後は曲(またはスライス)の長さ、完成後は動画の長さ。

startnumber | null

曲の中でスライスが始まる位置(秒)。曲全体を使うときは null。

endnumber | null

スライスが終わる位置(秒)——解析後、適用された値(曲の終わりを超える end は曲の終わりになります)。曲全体を使うときは null。

sizestring

リクエストしたアスペクト比(16:9、9:16、1:1)。完成後は動画のピクセル数(例:1472x832)。

modestring

image(キャラクタープロフィールあり)または text。

briefobject

送った story、style、character、locations(送らなかったものは null)。character_id があり character がないときは、character は保存したキャラクターの説明です。

character_idstring | null

動画の作成に使った保存したキャラクター、または null。

director_modelstring

シーンを書くチャットモデル。

image_modelstring | null

mode: "image" で参照シートと最初のフレームを描く画像モデル。

first_framesboolean

minimax-h3-music-video で最初のフレームも描くかどうか(作成リクエストの first_frames を参照)。

temponumber | null

解析で得た曲のテンポ(1 分あたりの拍数)。

languagestring | null

解析で歌詞を書き起こした言語。

characterstring | null

監督がキャスティングした歌い手:顔、髪、体つき(服装は含まない)。mode: "text" とキャスティングが終わるまでは null。

looksarray

歌い手のルック(衣装)、最大 4 つ。mode: "text" とキャスティングが終わるまでは空。

scenesarray

シーンごとに 1 項目、順番どおり。曲の解析が終わるまでは空。

errorobject | null

failed と cancelled の動画のみ:code と message(課金されたかどうかも書かれています)。

urlstring | null

completed になった完成版の mp4。動画をダウンロードするを参照。

hold_usdnumber

残高から保留されている金額:曲全体の料金。解析の終わりから動画の精算まで。それ以前は 0。

charge_usdnumber | null

精算後の動画の料金。それ以前は null。

other_usdnumber

監督のチャット呼び出しと、参照シートおよび最初のフレームの画像呼び出しにここまでかかった料金。それぞれの呼び出しとして課金され、charge_usd には含まれません。

powered_bystring

LTX または MiniMax H3。

The music video object
{
  "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"
}

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

POST/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:9

16: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デフォルト image

image:キャラクタープロフィール——監督が歌い手と最大 4 つのルックをキャスティングし、image_model がルックごとに参照シートを描き、各シーンはそのルックのシートから描いた最初のフレームから始まります(minimax-h3-music-video では各シーンをシートそのものから撮影します。first_frames を参照)。text:画像なし、各シーンをプロンプトだけから。キャラクタープロフィールが必要な minimax-h3-music-video では使えません。

image_modelstringデフォルト gpt-image-2

mode: "image" のみ。キーで使える画像モデルのうち、参照画像(編集)に対応したもの(例:gpt-image-2)。生成だけのモデルは 400 で拒否されます。通常の画像ジョブとして課金され、目安はルックごとに 1 枚とシーンごとに 1 枚です。

first_framesbooleanデフォルト false

minimax-h3-music-video のみ(他のモデルは mode: "image" で常に最初のフレームを描きます)。このモデルは最初のフレームなしで、ルックのシートから歌い手を撮影します。true にすると各シーンの冒頭のフレームも描き、シートと一緒にモデルに渡します。各シーンがどこで、どう始まるかをより細かく決められる代わりに、シーンごとに画像が 1 枚増え、レンダリングも遅くなります。その場合、動画は 1 秒あたり $0.13 ではなく $0.2 で課金されます。

character_imagefile or string

mode: "image" のみ。歌い手の画像で、ルック 1 のシートの元になります:PNG、JPEG、WebP、最大 20 MB、ファイルまたは URL(character_image_url でも可)。

character_idstring

mode: "image" のみ。あなたのアカウントの保存したキャラクター:そのシートが character_image と同じように使われ、character を送らなければその説明が character として使われます。character_image とは併用できません。

director_modelstringデフォルト gemini-3.8-flash

シーンを書くチャットモデル。キーで使える任意のチャットモデル。通常のチャット呼び出しとして課金。

scene_secondsnumberデフォルト 5

目標とするシーンの長さ、2〜10 秒。カットはビートに合わせるので、シーンの長さはこの前後で変わります。

auto_renderbooleanデフォルト true

false:シーンが書けて最初のフレームが描けた時点でステータス ready で止まり、レンダリング前に編集できます。

seedinteger

再現可能なシーン(0〜2147483647)。デフォルト:ランダム。

クエリパラメータ

waitinteger

0〜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
Response
{
  "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"
}

ミュージックビデオを取得する#

GET/v1/videos/music/{id}

ミュージックビデオオブジェクトを返します。status が completed、failed、cancelled になるまでポーリングしてください。

クエリパラメータ

waitinteger

0〜300。ロングポーリング:ステップが変わるか次のシーンが完成した時点で、そうでなければ時間切れで返ります。ready の動画はすぐに返ります。

curl "https://lovelyrouter.com/v1/videos/music/MUSIC_ID?wait=120" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

ミュージックビデオを一覧表示する#

GET/v1/videos/music

あなたのミュージックビデオ。新しい順。

クエリパラメータ

limitintegerデフォルト 20

1〜100。

afterstring

ミュージックビデオの ID:それより前に作られたものを一覧表示します(次のページ)。

cURL
curl "https://lovelyrouter.com/v1/videos/music?limit=10" \
  -H "Authorization: Bearer $LOVELY_API_KEY"
Response
{
  "object": "list",
  "data": [{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video", "status": "completed" }],
  "first_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "last_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "has_more": false
}

シーンを編集する#

PATCH/v1/videos/music/{id}

動画が ready(auto_render: false で作成)の間、シーンのプロンプトを書き直します。送ったプロンプトはシーンの prompt をそのまま置き換えます——キャラクター、ルック、style は改めて加えられないので、プロンプトに残してください。mode: "image" では最初のフレームはもう描かれています。新しいプロンプトはシーンの動きを変えますが、最初のフレームは変えません。ミュージックビデオオブジェクトを返します。他のステータスでは 409。

ボディパラメータ

scenesarray必須

変更するシーン。

cURL
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."}]}'

ミュージックビデオをレンダリングする#

POST/v1/videos/music/{id}/render

ready の動画のレンダリングを始めます。in_progress になったミュージックビデオオブジェクトを返します。他のステータスでは 409。1 日以内にレンダリングされなかったプランは、料金なしでキャンセルされます。

cURL
curl -X POST https://lovelyrouter.com/v1/videos/music/MUSIC_ID/render \
  -H "Authorization: Bearer $LOVELY_API_KEY"

動画をダウンロードする#

GET/v1/videos/music/{id}/content

完成した mp4。サウンドトラックはその曲です。Range リクエストに対応しているので、プレーヤーでシークできます。7 日間保存。completed になる前は 409、削除または期限切れの後は 410。

cURL
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o music-video.mp4

シーンをダウンロードする#

GET/v1/videos/music/{id}/scenes/{n}/content

レンダリング済みの 1 シーンの mp4(その部分の曲付き)。動画全体の完成を待たず、そのシーンが done になればすぐに取得できます。n はシーンの index。レンダリング前は 409。

cURL
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/scenes/0/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o scene-0.mp4

ルックのシートをダウンロードする#

GET/v1/videos/music/{id}/looks/{n}/content

ルックのターンアラウンド参照シート(正面、斜め、横、背面)。描き終わればすぐ、プランニング中、どのシーンもレンダリングされる前に取得できます。n はルックの id(1 から)。まだ描かれていないときと mode: "text" では 404。

cURL
curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/looks/1/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o look-1.png

削除#

DELETE/v1/videos/music/{id}

終わった動画(completed、failed、cancelled):ファイルを削除し、一覧から外します。ready で待っているプラン(auto_render: false):破棄します。料金はかかりません。分析やレンダリングを始めた動画は止められません:409 を返します。終わるのを待ってから削除してください。

cURL
curl -X DELETE https://lovelyrouter.com/v1/videos/music/MUSIC_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"
Response (deleted)
{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video.deleted", "deleted": true }

エラー#

エラーは標準のエラーボディを使います。開始後に失敗した動画は HTTP エラーではありません:status が failed になり、error に理由が入ります。

ステータスtype / code理由
400consent_requiredconsent が true ではありません。
400invalid_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。
401authentication_errorAPI キーがないか無効です。
402insufficient_quota残高、またはキーの利用上限が、最短の動画に足りません。
404not_found_error不明なモデルまたはミュージックビデオ、ミュージックビデオを作らないモデル、あなたの保存したキャラクターではない character_id、またはシートがまだ描かれていないルック。
409invalid_request_errorready でない動画の編集やレンダリング、またはまだレンダリングされていないファイルのダウンロード。
410not_found_error動画は削除されたか期限切れです。
429rate_limit_exceededアカウントでミュージックビデオがすでに 2 本進行中、またはキーのレート制限。

失敗した動画には次のいずれかの error.code が付きます:invalid_request_error(曲を使えなかった。5 秒未満や 6 分超、または曲の終わりを超える start など)、insufficient_quota(残高が曲全体に足りなかった)、capacity_exhausted(GPU が空かなかった)、api_error(当社側の問題)、expired(ready のプランが 1 日待った)、cancelled(ready で破棄したプラン)。どの場合も動画の料金はかかりません。