API リファレンス

動画ショットのエンドポイント

/v1/videos/shots、/v1/videos/joins、/v1/videos/projects のすべてのエンドポイント——キャラクターとシーンをタグ付けしたプロンプトからショットをレンダリングし、完成したショットを無料で 1 本の動画につなぎ、絵コンテをプロジェクトとして保存します。

ショットは、プロンプトと画像から作る数秒の動画です。プロンプトの中で保存したキャラクターやシーンをタグ付けすると——@Mia_Wong、@[Night Café]、@chr_…——タグ付けされたものがそれぞれ参照画像になります。人物の顔、髪、服装はその画像から、場所の見た目はその画像から引き継がれ、ショットには音とセリフが付きます。ショットを 1 つずつレンダリングし、完成したショットを無料で 1 本の動画につなげます。

エンドポイントは https://lovelyrouter.com/v1/videos 以下にあります。API キーを Authorization: Bearer $LOVELY_API_KEY として送って認証します（認証）。モデルは minimax-h3-video で、MiniMax H3 を使い、MiniMax H3 の規約の対象です：すべてのショットで consent: true を指定します。コードなしで試すには Playground をどうぞ。

タグと画像#

どの画像を使うかはプロンプトが決めます。ショットで使える可能性のあるキャラクターとシーンを characters と scenes に並べ（プロジェクトのライブラリ全体を送っても構いません）、プロンプトがタグ付けしたものが、最初に登場した順に画像になります。

@handle——名前の空白を _ にしたもの：Mia Wong → @Mia_Wong。大文字小文字は区別しません。
@[Full Name]——書いたままの任意の名前：@[Night Café]。
@chr_… / @scn_…——ID。同じ名前が 2 つあるときに使います。

二重引用符の中の言葉はセリフで、その直前に最後にタグ付けされたキャラクターが話します：@Leo looks up: "You came."。服装や顔は書かないでください——画像が伝えます。1 ショットの画像は 1〜9 枚です。タグのないプロンプトでは、並べたキャラクターが 1 人だけ（シーンも 1 つだけ）ならそれを使います。

声#

タグ付けされたキャラクターに声があれば、それを持ち込みます：セリフはその声で話されます（声質、高さ、話し方を借り、内容や背景音は借りません）。1 ショットで画像の順に最初の 3 人の声のあるキャラクターが自分の声を持ち込みます——モデルが受け取れる音声参照は最大 3 つで、それ以外はモデルが声を付けます。インラインのキャラクターも voice を持てます：保存したボイスの ID（voice_…）か、サンプルの http(s) / data: の URL。声で料金は変わりません。

誰が誰か：プロンプトの整理#

動画モデルにはどの言葉が誰のことかを分かってもらう必要があるため、セリフの外の代名詞——he、she、his、her、they（と他、她、彼、彼女）——がモデルに届くことはありません。ショットのレンダリング前に：

キャラクターが 1 人：代名詞はすべてそのキャラクターのタグになります（her coat → @Mia's coat）。即時、無料です。
2 人以上：チャットモデル（sweep_model、既定は gemini-3.8-flash）が、すべての人物を毎回タグで呼ぶようにプロンプトを書き直します。答えはチェックされ——同じタグ、セリフは一字一句同じ、代名詞なし——通らなければもう一度試し、それでも通らなければ送ったとおりのプロンプトでレンダリングします。整理のせいでショットが失敗することはありません。

実際にレンダリングしたプロンプトはショットの prompt_rendered（変更がなければ null）、prompt は送ったままです。チャット呼び出しは同じキーの通常のチャットリクエストとして課金され、other_usd に表示されます。ショットの料金には含まれません。書いたとおりにレンダリングするには sweep: false を送ります。二重引用符の中の言葉は決して変えません。

料金#

ショットは実際にレンダリングされた秒数で課金されます：モデルは 24 fps、17k+5 フレーム単位でレンダリングするため（最低 124 フレーム）、5 秒のショットは 5.17 秒、10 秒のショットは 10.13 秒になります——ショットオブジェクトの rendered_seconds です。画像 1 枚ならレンダリング 1 秒あたり $0.13、2 枚目以降は 1 枚ごとに 1 秒あたり $0.06 が加わります：キャラクター 2 人とシーン 1 つの 5 秒ショットは（$0.13 + 2 × $0.06）× 5.17 秒です。送信時に料金を確保し、ショットの完成時に請求します。失敗・キャンセルしたショットは無料です。結合とプロジェクトも無料です。

ショットオブジェクト#

属性

idstring

shot_ に続く 24 文字。

objectstring

常に video.shot。

statusstring

queued、in_progress、completed、failed、cancelled のいずれか。

progressinteger

0〜100。レンダリング中は推定値です。

promptstring

送ったとおりのプロンプト。

prompt_renderedstring | null

整理で変更があったときの、整理後のプロンプト。

secondsnumber

指定した長さ（5〜15）。

rendered_secondsnumber

レンダリングされ課金される長さ。

sizestring

16:9、9:16、1:1。完成後の width と height がピクセル数です。

referencesarray

タグ付けされたキャラクターとシーンを画像の順に：{picture, kind, name, id}（インラインのものは id が null）。続いて、一緒に持ち込まれた声を順に：{audio, kind, name, id}（audio = 1–3）。

project_idstring | null

所属するプロジェクト。

urlstring | null

completed になったあとの mp4。7 日間保持されます。

hold_usd、`charge_usd` number

確保した金額と、精算後の請求額。

other_usdnumber

整理のチャット呼び出し。同じキーでチャットとして課金されます（hold_usd / charge_usd には含まれません）。

errorobject | null

失敗したときの {code, message}。

ショットオブジェクト

{
  "id": "shot_8c1f0a7d3b9e4c2a6f5d1e0b",
  "object": "video.shot",
  "model": "minimax-h3-video",
  "status": "completed",
  "progress": 100,
  "project_id": "prj_2a9e7c1b5d3f4e6a8c0b1d2e",
  "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
  "prompt_rendered": null,
  "seconds": 5,
  "rendered_seconds": 5.167,
  "size": "16:9",
  "width": 1344,
  "height": 768,
  "seed": null,
  "language": "en",
  "style": null,
  "references": [
    { "picture": 1, "kind": "scene", "name": "Night Café", "id": "scn_5b2d9e0c1a7f4b3e8d6c2a1f" },
    { "picture": 2, "kind": "character", "name": "Leo", "id": "chr_1e4b7d0a9c3f2e5b8a6d0c1f" },
    { "picture": 3, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" },
    { "audio": 1, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" }
  ],
  "url": "https://lovelyrouter.com/v1/videos/shots/shot_8c1f0a7d3b9e4c2a6f5d1e0b/content",
  "hold_usd": 1.291667,
  "charge_usd": 1.291667,
  "other_usd": 0,
  "error": null,
  "powered_by": "MiniMax H3"
}

ショットを作成する#

POST/v1/videos/shots

ショットを開始し、202 とショットオブジェクトを返します（wait 内に完成すれば 200）。JSON、または characters / scenes を JSON テキストフィールドにした multipart で送ります。

ボディパラメータ

modelstring必須

minimax-h3-video。

promptstring必須

何が起きるか。キャラクターとシーンをタグ付けします。最大 4,000 文字。

consentboolean必須

true で MiniMax H3 の規約に同意します。

charactersarray

保存したキャラクターの ID（chr_…）、またはインラインの {name, image, description?}。image は http(s) か data: の URL——multipart ではファイルパートの名前でも構いません。インラインのキャラクターには voice も付けられます：保存したボイスの ID、またはサンプルの http(s) / data: の URL（声を参照）。

scenesarray

保存したシーンの ID（scn_…）、またはインラインの {name, image, description?}。

secondsnumberデフォルト 5

5〜15。

sizestringデフォルト 16:9

16:9、9:16、1:1。

languagestring

セリフの言語。例：en、zh、ja。既定は英語。

stylestring

映像のスタイル。例：warm 35mm film。既定は実写。

seedinteger

0〜2147483647。再現可能な結果のために。

sweepbooleanデフォルト true

false で整理せず、書いたとおりにレンダリングします。

sweep_modelstringデフォルト gemini-3.8-flash

ショットに 2 人以上いるとき、全員をタグで呼ぶチャットモデル。キーで使える任意のチャットモデル。

project_idstring

紐づける自分のプロジェクト。

waitinteger

0〜300 秒。完成するまでリクエストを保持します（?wait= も可）。

Shell

curl https://lovelyrouter.com/v1/videos/shots \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "minimax-h3-video",
    "consent": true,
    "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
    "characters": ["chr_3b9e1f0c7a2d4e58b6c1a9f2", "chr_1e4b7d0a9c3f2e5b8a6d0c1f"],
    "scenes": ["scn_5b2d9e0c1a7f4b3e8d6c2a1f"],
    "seconds": 5
  }'

ショットの取得・一覧・削除#

GET/v1/videos/shots/{id}

ショットオブジェクトを返します。?wait=1–300 で完成するか時間切れになるまで待ちます。GET /v1/videos/shots/{id}/content は mp4 です（Range リクエスト対応）。GET /v1/videos/shots は新しい順の一覧です：?limit=1–100、次のページは ?before=<ショット ID>、1 つのプロジェクトのものだけなら ?project_id=。

DELETE /v1/videos/shots/{id} はショットを一覧から外し、ファイルを削除します。キュー中のショットは無料でキャンセルされます。すでにレンダリング中のショットは最後まで処理され、課金されます。

cURL

curl "https://lovelyrouter.com/v1/videos/shots/SHOT_ID?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl https://lovelyrouter.com/v1/videos/shots/SHOT_ID/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o shot.mp4

ショットを結合する#

POST/v1/videos/joins

完成した自分のショットを、指定した順に 1 本の動画につなげます。各ショットの音はそのまま残ります。無料です。ショットはサイズが同じで、7 日以内のものである必要があります。202 と結合オブジェクトを返します：{id: "join_…", object: "video.join", status, shots, size, seconds, width, height, url, charge_usd: 0}。GET /v1/videos/joins/{id}（?wait= 可）、/content、GET /v1/videos/joins、DELETE はショットと同じように使えます。

ボディパラメータ

shotsarray必須

2〜50 個のショット ID。再生順に並べます。

project_idstring

紐づける自分のプロジェクト。

cURL

curl https://lovelyrouter.com/v1/videos/joins \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"shots": ["shot_8c1f0a7d3b9e4c2a6f5d1e0b", "shot_0d2e4f6a8b1c3e5d7f9a0b2c"]}'

プロジェクト#

POST/v1/videos/projects

プロジェクトは絵コンテを保存します：名前と、自由に使える JSON ドキュメント（doc）——Playground はここにサイズ、スタイル、言語、ショット、キャラクター、シーンを保存します。無料で、1 アカウント最大 100 件。POST は {name?, doc?} を受け取り、201 と {id: "prj_…", object: "video.project", name, doc, created_at, updated_at} を返します。

リクエスト	内容
`GET /v1/videos/projects`	自分のプロジェクト。最近変更した順で、`doc` は含みません（`?limit`、`?after`）。
`GET /v1/videos/projects/{id}`	1 件のプロジェクト（`doc` 付き）。
`PATCH /v1/videos/projects/{id}`	`{name?, doc?}`。`doc` は丸ごと置き換え、最大 200 KB。
`DELETE /v1/videos/projects/{id}`	プロジェクトを削除します。ショットは残ります。

cURL

curl https://lovelyrouter.com/v1/videos/projects \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Night café", "doc": {"size": "16:9", "shots": []}}'

エラー#

エラーは標準のエラーボディを使います。プロンプトのエラーには code と該当する tags が付きます。

ステータス	`code` / `type`	理由
`400`	`unknown_tags`	`characters` や `scenes` にない名前をプロンプトがタグ付けしています。`error.tags` に一覧があります。
`400`	`ambiguous_tag`	並べたキャラクターやシーンのうち 2 つが、タグ付けされた名前と同じです：ID でタグ付けしてください。
`400`	`no_pictures` / `too_many_pictures`	画像がない、または 9 枚を超えています。
`400`	`consent_required`	`consent` が `true` ではありません。
`400`	`mixed_sizes`	サイズの異なるショットを結合しようとしました。
`400`	`invalid_request_error`	範囲外のフィールド、読めない画像、合計 24 MB を超える画像、完成していない・期限切れのショットの結合。
`402`	`insufficient_quota`	残高が確保額に足りません。
`404`	`not_found_error`	不明なモデル、ショット、結合、プロジェクト、キャラクター、シーン、または他のアカウントのもの。
`429`	`rate_limit_exceeded`	アカウントですでに 5 件のショットか結合がキュー中またはレンダリング中です。