API リファレンス

キャラクターのエンドポイント

/v1/characters と /v1/scenes のすべてのエンドポイント——キャラクター（名前、説明、ターンアラウンドシート）やシーン（場所とその画像）の保存、一覧表示、取得、更新、削除、画像のダウンロード、そしてミュージックビデオ、キャラクタースワップ、動画ショットでの利用。

保存したキャラクターは、繰り返し使いたい人物です：名前、説明（顔、髪、体つき、いつもの服装）、ターンアラウンドシート——同じ人物の正面、斜め、横、背面と、その下に 6 つの表情の顔のクローズアップを 1 枚にした画像——に加え、任意でその元になった写真と声。毎回画像を送る代わりに、その ID を character_id としてミュージックビデオやキャラクタースワップに渡します。

キャラクターの保存は任意です。どの動画エンドポイントも引き続き画像とテキストを直接受け付けるので、1 回限りの呼び出しには保存したキャラクターはまったく必要ありません。

エンドポイントは https://lovelyrouter.com/v1/characters 以下にあります。API キーを Authorization: Bearer $LOVELY_API_KEY として送って認証します（認証）。キャラクターの保存は無料で、あなたのアカウントだけのもので、削除するまで残ります。1 アカウントで最大 100 件まで保存できます。

キャラクターオブジェクト#

属性

idstring

一意の ID。chr_ に続く 24 文字。

objectstring

常に character。

namestring

キャラクターの呼び名、最大 80 文字。

descriptionstring

その人物について書いたとおりの内容：顔、髪、体つき、いつもの服装。最大 4,000 文字。空でも構いません。

sheet_urlstring

ターンアラウンドシート。画像をダウンロードするを参照。シートを差し替えるとクエリの v の値が変わります。

photo_urlstring | null

元の写真。保存した場合のみ。

voiceobject | null

動画ショットでのキャラクターの声：id（保存したボイス）、description（どう設計したか、または null）、audio_url（サンプル）。声がないときは null。キャラクターに声を付けるを参照。

created_atinteger

Unix 秒。

updated_atinteger

最後に変更した時刻（Unix 秒）。

The character object

{
  "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "object": "character",
  "name": "Mara",
  "description": "A woman in her thirties with a long black braid, brown eyes, freckles and an athletic build; a green bomber jacket over a grey hoodie, black cargo trousers and white sneakers.",
  "sheet_url": "https://lovelyrouter.com/v1/characters/chr_3b9e1f0c7a2d4e58b6c1a9f2/sheet?v=mh2x7k1c",
  "photo_url": null,
  "voice": {
    "id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f",
    "description": "A low, calm alto, unhurried",
    "audio_url": "https://lovelyrouter.com/v1/audio/voices/voice_7d2a9c4e1b6f3a8d0c5e2b1f/audio"
  },
  "created_at": 1792915200,
  "updated_at": 1792915200
}

キャラクターを作成する#

POST/v1/characters

キャラクターを保存し、201 とキャラクターオブジェクトを返します。multipart（sheet と photo をファイルとして）か JSON（同じものを http(s) または data: の URL で）で送ります。画像 API で生成したシートを保存するには、ファイルの代わりに画像ジョブの ID を sheet_image_job として渡します。

ボディパラメータ

namestring必須

最大 80 文字。

descriptionstring

顔、髪、体つき、いつもの服装、最大 4,000 文字。character のブリーフを送らなかったとき、ミュージックビデオはこれをそのブリーフとして使います。

sheetfile or string必須

ターンアラウンドシート：PNG、JPEG、WebP、最大 10 MB、ファイルまたは http(s) / data: の URL（sheet_url でも可）。画像ジョブから取るには代わりに sheet_image_job を使います。

sheet_image_jobstring

あなたのアカウントの succeeded になった画像ジョブの ID（img_…）：その最初の画像がシートになります。これか sheet のどちらかを送ります。

photofile or string

シートの元になった写真。PNG、JPEG、WebP、最大 10 MB（photo_url または photo_image_job でも可）。記録用に保存されるもので、動画にはシートが使われます。

voice_idstring

キャラクターに付ける保存したボイス（voice_…）。

voicefile or string

代わりに新しいボイスサンプル：WAV、MP3、OGG/Opus、FLAC、M4A、WebM、最大 10 MB、ファイルまたは http(s) / data: の URL。キャラクターの名前でボイスとして保存され、リンクされます。consent が必要です。

voice_transcriptstring

サンプルで話している内容（最大 1,000 文字）——あるとよりよく声を再現できます。

consentboolean

true で、サンプルがあなた自身の声か、話者の許可を得ていることを確認します。voice を送るときは必須。

voice_descriptionstring

その声をどう設計したか。例：qwen3-tts に渡した説明（最大 1,000 文字）。記録用にボイスと一緒に保存されます。

Shell

curl https://lovelyrouter.com/v1/characters \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name=Mara \
  -F description="A woman in her thirties with a long black braid, brown eyes and freckles; a green bomber jacket" \
  -F sheet=@mara-sheet.png

キャラクターを一覧表示する#

GET/v1/characters

あなたのキャラクター。新しい順。

クエリパラメータ

limitintegerデフォルト 20

1〜100。

afterstring

キャラクターの ID：それより前に保存されたものを一覧表示します（次のページ）。

cURL

curl "https://lovelyrouter.com/v1/characters?limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character", "name": "Mara" }],
  "first_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "last_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "has_more": false
}

キャラクターを取得する#

GET/v1/characters/{id}

キャラクターオブジェクトを返します。あなたのものでない ID には 404。

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

キャラクターを更新する#

PATCH/v1/characters/{id}

送ったフィールドを変更し、キャラクターオブジェクトを返します。作成と同じく JSON または multipart を受け付けます。すでに作られた動画は、作成時のシートのままです。

ボディパラメータ

namestring

新しい名前。

descriptionstring

新しい説明（空文字列で消去）。

sheetfile or string

新しいシート、または sheet_image_job。

photofile

新しい写真（または photo_image_job）。null で削除します。

voice_idstring or null

保存したボイスをリンクします。null でリンクを外します（保存したボイス自体は残ります）。

voicefile

新しいサンプル（voice_transcript と consent とともに、作成と同じ）。null でリンクを外します。

voice_descriptionstring or null

その声をどう設計したか。新しくリンクしたボイスには、一緒に送った説明が付きます（なければなし）。

cURL

curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"description": "A woman in her thirties with a long black braid, now in a red raincoat"}'

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

GET/v1/characters/{id}/sheet

シートの画像。元のコンテンツタイプのまま返します。GET /v1/characters/{id}/photo は写真です（ない場合は 404）。読めるのはあなたのキーだけです。

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID/sheet \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o sheet.png

キャラクターを削除する#

DELETE/v1/characters/{id}

キャラクターとその画像を削除します。すでにそのキャラクターで作られた動画には影響しません。

cURL

curl -X DELETE https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character.deleted", "deleted": true }

キャラクターに声を付ける#

キャラクターには声を付けられます：あなたの保存したボイスの 1 つです。動画ショットでは、声のあるキャラクターはその声でセリフを話します——借りるのは声質、高さ、話し方で、話す内容ではありません。

アップロード：キャラクターの作成時または更新時に、サンプルを voice として送ります（voice_transcript と consent: true とともに）。キャラクターの名前でボイスとして保存されます。
デザイン：qwen3-tts で、説明とそのキャラクターが言いそうなセリフからサンプルを作り（instructions = 説明、input = セリフ、voice なし）、POST /v1/audio/voices で保存して、voice_id としてリンクします——説明は voice_description に。

voice_id: null（または voice: null）でリンクを外します。キャラクターを削除してもボイスは残り、ボイスを削除するとすべてのキャラクターからリンクが外れます。

cURL

# 保存したボイスをキャラクターにリンクする。
curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"voice_id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f", "voice_description": "A low, calm alto, unhurried"}'

保存したシーン#

POST/v1/scenes

保存したシーンは、動画ショットで繰り返し使いたい場所です：名前、場所の説明、その画像。シーンはキャラクターと同じように https://lovelyrouter.com/v1/scenes 以下で使え、画像のフィールド名は image（ファイル、http(s) / data: の URL、または image_image_job）で、写真はありません。キャラクターとは別に 1 アカウント最大 100 件、無料です。

シーンオブジェクト：{id: "scn_…", object: "scene", name, description, image_url, created_at, updated_at}。

リクエスト	内容
`POST /v1/scenes`	`name`（必須、最大 80 文字）、`description`、`image`（必須）。`201` を返します。
`GET /v1/scenes`	自分のシーン、新しい順（`?limit`、`?after`）。
`GET /v1/scenes/{id}`	1 件のシーン。
`PATCH /v1/scenes/{id}`	`name`、`description`、`image`。
`GET /v1/scenes/{id}/image`	画像（自分のキーでのみ取得可）。
`DELETE /v1/scenes/{id}`	シーンとその画像を削除します。

cURL

curl https://lovelyrouter.com/v1/scenes \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name="Night Café" \
  -F description="A small café at night, rain on the windows, warm lamps" \
  -F image=@cafe.jpg

キャラクターを使う#

画像を送る場所で character_id を渡します。直接送るフィールドも引き続き使えるので、呼び出しごとに選べます：

エンドポイント	1 回限りの呼び出し（直接送る）	保存したキャラクターで
`POST /v1/videos/music`	`character`（テキスト）と／または `character_image`（ファイルまたは URL）	`character_id`：そのシートが参照画像になり、`character` を送らなければその説明が `character` のテキストになります。`character_image` とは併用できず、`mode: "image"` のときのみ。
`POST /v1/videos`	`input_reference`（ファイルまたは URL）	`character_id`：そのシートが参照画像になります。どちらか一方だけを送ります。
`POST /v1/videos/shots`	`characters` / `scenes`：`{name, image}` オブジェクト	`characters` / `scenes`：ID。プロンプトでタグ付けし（`@Mara`）、タグ付けされたものがそれぞれ参照画像になります。

ミュージックビデオオブジェクトと動画オブジェクトには、作成に使った character_id が表示されます（直接送った呼び出しでは null）。

cURL

# 1 回限りのミュージックビデオ：画像を呼び出しと一緒に送ります。
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character="A woman with a long black braid" -F character_image=@mara.png

# 同じものを保存したキャラクターで。
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2

エラー#

エラーは標準のエラーボディを使います。

ステータス	`type`	理由
`400`	`invalid_request_error`	`name` や `sheet` がない、フィールドが長すぎる、画像が PNG、JPEG、WebP でないか 10 MB を超える、画像ジョブがあなたのものでないか成功していない、またはすでに 100 件のキャラクターを保存済み。`voice_id` があなたのボイスでない、`voice` が音声でないか 10 MB を超える、`consent` なしで `voice` を送った、またはすでに 100 件のボイスを保存済み。
`401`	`authentication_error`	API キーがないか無効です。
`404`	`not_found_error`	不明または削除済みのキャラクター、または別のアカウントのキャラクター——動画のリクエストの `character_id` でも同じです。