> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Luma ビデオ生成 API 接続説明
> Luma Video Generation 集成指南 - XHuoAPI
AI の応用が広がるにつれて、さまざまな AI プログラムが徐々に普及しています。AI は人々の仕事や生活のあらゆる面に深く浸透しています。そして、AI が関与する業界もますます増えています。最初の執筆から、医療教育、そして現在のビデオへと進化しています。
Luma は専門的で高品質なビデオ生成プラットフォームで、ユーザーは素材をアップロードするだけで、異なるスタイルや効果に基づいて自動的に高品質なビデオを生成できます。この AI ビデオ生成器は、著名なテクノロジー企業のチームメンバーによって開発されており、複雑な編集ツールを必要とせず、誰でも簡単に素晴らしいビデオを制作できることを目指しています。
しかし、Luma 公式は API を提供していません。XHuoAPI は Luma の API を提供し、Suno 公式との接続を模倣して、簡単かつ迅速に希望するビデオを生成できるようにしています。
## 申請と使用
Luma Videos API を使用するには、まず [Luma Videos Generation API](https://api.xhuoapi.ai/documents/5bd3597d-1ff8-44ad-a580-b66b48393e7f) ページにアクセスし、「Acquire」ボタンをクリックして、リクエストに必要な認証情報を取得します：
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。
初回申請時には無料のクレジットが付与され、この API を無料で使用できます。
## 基本使用
生成したいビデオに関して、任意のテキストを入力できます。例えば、宇宙と火山の間を行き来する宇宙飛行士に関するビデオを生成したい場合は、`Astronauts shuttle from space to volcano` と入力します。以下のようになります：
生成されたコードは以下の通りです：
主なリクエストパラメータ：
* `prompt`：生成するビデオのプロンプト。
* `aspect_ratio`：ビデオのアスペクト比、デフォルトは 16:9。
* `end_image_url`：オプション、指定された尾フレーム。
* `enhancement`：オプション、鮮明度向上スイッチ。
* `loop`：ループビデオを生成するかどうか、デフォルトは false。
* `timeout`：オプション、タイムアウト秒数。
* `callback_url`：非同期コールバックアドレス。
「Try」ボタンをクリックして直接 API をテストできます。1-2 分待つと、結果は以下のようになります：
```json theme={null}
{
"success": true,
"task_id": "e4018a99-1522-4f24-9330-62c2a9b50b59",
"video_id": "155838f8-7f1e-44d8-b387-192f3b4b509d",
"prompt": "Astronauts shuttle from space to volcano",
"video_url": "https://storage.cdn-luma.com/dream_machine/af94e7ca-da35-4b5f-a636-2d7254184d0d/watermarked_video0585de3737db946e5a0ac895384ecd180.mp4",
"video_height": 752,
"video_width": 1360,
"state": "completed",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/e4018a99-1522-4f24-9330-62c2a9b50b59.jpg",
"thumbnail_width": 1360,
"thumbnail_height": 752
}
```
この時点で、ビデオの関連情報が得られました。ビデオID、ビデオリンク、ビデオサムネイルなどの内容が含まれています。
フィールドの説明は以下の通りです：
* success：生成が成功したかどうか、成功した場合は `true`、そうでない場合は `false`
* task\_id：このビデオ生成タスクのユニークID
* video\_id：このビデオ生成タスクから生成されたビデオのユニークID
* prompt：このビデオ生成タスクのキーワード
* video\_url：このビデオ生成タスクの結果ビデオリンク
* video\_height：生成後のビデオサムネイル画像の高さ
* video\_width：生成後のビデオサムネイル画像の幅
* state：このビデオ生成タスクの状態、タスクが完了した場合は `completed`。
* thumbnail\_url：生成後のビデオサムネイル画像のリンク
* thumbnail\_width：生成後のビデオサムネイル画像の幅
* thumbnail\_height：生成後のビデオサムネイル画像の高さ
## カスタムの先頭と尾フレーム生成
カスタムビデオの先頭と尾フレームを使用してビデオを生成したい場合は、先頭と尾フレームの画像リンクを入力できます：
この時、ビデオの先頭フレーム `start_image_url` フィールドには、以下の画像をビデオの先頭フレームとして渡すことができます：
次に、先頭と尾フレーム、キーワードに基づいてカスタムビデオを生成するために、以下の内容を指定できます：
* action：ビデオ生成タスクのアクション、通常は普通生成 `generate` と拡張生成 `extend`、デフォルトは `generate`。
* start\_image\_url：生成するビデオの先頭フレームを指定。
* end\_image\_url：生成するビデオの尾フレームを指定。
* prompt：生成するビデオのキーワード内容。
記入例は以下の通りです：
記入が完了すると、自動的に生成されたコードは以下の通りです：
対応するコード：
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/luma/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"start_image_url": "https://cdn.xhuoapi.ai/r9vsv9.png",
"action": "generate",
"prompt": "Astronauts shuttle from space to volcano"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
得られた結果は以下の通りです：
```json theme={null}
{
"success": true,
"task_id": "12a18694-fd4b-47e7-9c50-34f30862cff6",
"video_id": "0105c090-03a5-425a-8026-523341cd575b",
"prompt": "Astronauts shuttle from space to volcano",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4",
"video_height": 656,
"video_width": 1552,
"state": "completed",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.jpg",
"thumbnail_width": 1552,
"thumbnail_height": 656
}
```
最後に得られた結果は前述のものと似ており、生成されたビデオの先頭フレームには渡した画像が含まれています。もちろん、先頭と尾フレームの画像リンクを同時に渡してビデオを生成することも可能です。上記の内容に尾フレーム画像を追加するだけで済みます。尾フレームの画像情報は以下の通りです：
記入例は以下の通りです：
最後に得られた結果は以下の通りです：
```json theme={null}
{
"success": true,
"task_id": "d1cb723a-e554-4775-94a4-bb6ae8c7ea67",
"video_id": "6bebd0d2-f793-472e-9326-38528a9273bb",
"prompt": "宇宙飛行士が宇宙から火山へ移動する",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.mp4",
"video_height": 656,
"video_width": 1552,
"state": "完了",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.jpg",
"thumbnail_width": 1552,
"thumbnail_height": 656
}
```
結果は上記と似ており、生成されたビデオには最初のフレームと最後のフレームの画像が含まれており、これによりカスタムの最初と最後のフレームを使用してビデオを生成することが完了しました。
## ビデオ拡張機能
生成されたビデオをさらに生成したい場合は、パラメータ `action` を `extend` に設定し、続けて生成するビデオのIDまたはビデオリンクを入力します。ビデオIDとビデオリンクの取得は基本的な使用に基づいて行います。以下の図を参照してください：
この時、ビデオのIDは次のようになります：
```
"video_id": "0105c090-03a5-425a-8026-523341cd575b",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4"
```
> 注意：ここでのビデオの `video_id` と `video_url` は生成後のビデオのIDとビデオリンクです。ビデオの生成方法がわからない場合は、上記の基本的な使用を参照してビデオを生成してください。
ビデオを続けて生成するには、ビデオリンクまたはビデオのIDをアップロードする必要があります。以下にビデオIDを使用して拡張する方法を示します。次に、キーワードを入力してカスタムビデオを生成する必要があります。以下の内容を指定できます：
* action：この時、ビデオを拡張する行動で、ここでは `extend` です。
* prompt：拡張するビデオのキーワード。
* video\_url：拡張生成するビデオのリンク。
* video\_id：拡張生成するビデオのユニークID。
* end\_image\_url：拡張生成するビデオに指定する最後のフレームの画像リンク（オプション）。
記入例は以下の通りです：
記入が完了すると、自動的に生成されたコードは以下の通りです：
対応するPythonコード：
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/luma/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"action": "extend",
"video_id": "0105c090-03a5-425a-8026-523341cd575b",
"prompt": "宇宙飛行士が宇宙から火山へ移動する"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
実行すると、次のような結果が得られます：
```json theme={null}
{
"success": true,
"task_id": "c6e529d1-a06d-4c12-91b2-c855135131c3",
"video_id": "36908c49-c2bb-4a11-bd5a-b8512b004818",
"prompt": "宇宙飛行士が宇宙から火山へ移動する",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.mp4",
"video_height": 656,
"video_width": 1552,
"state": "完了",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.jpg",
"thumbnail_width": 1552,
"thumbnail_height": 656
}
```
このビデオは、拡張が必要なビデオを基に拡張されたことがわかります。結果の内容は上記と一致しており、これにより曲の続きの生成機能が実現されました。
もちろん、ビデオのリンクを指定して拡張生成することもできます。以下の情報を入力します：
実行後、次のような結果が得られました：
```json theme={null}
{
"success": true,
"task_id": "1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca",
"video_id": "f0187dc2-339f-4a08-a435-c3a3341f620a",
"prompt": "宇宙飛行士が宇宙から火山へ移動する",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.mp4",
"video_height": 656,
"video_width": 1552,
"state": "完了",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.jpg",
"thumbnail_width": 1552,
"thumbnail_height": 656
}
```
結果から、ビデオリンクに基づいてビデオ拡張機能が実現できることがわかります。
最後に、拡張ビデオに指定した最後のフレーム画像を追加して拡張することもできます。以下は最後のフレーム画像の情報です：
次に、上記の基礎の上に最後のフレーム画像情報を追加します。具体的には以下の通りです：
実行すると、次のような情報が得られます：
```json theme={null}
{
"success": true,
"task_id": "b816b2b4-c345-4673-9e19-83e91f91b643",
"video_id": "c5400053-63e6-4206-8082-31cf9dd1e7ed",
"prompt": "宇宙飛行士が宇宙から火山へ移動する",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.mp4",
"video_height": 656,
"video_width": 1552,
"state": "完了",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.jpg",
"thumbnail_width": 1552,
"thumbnail_height": 656
}
```
上記の拡張ビデオの基礎の上に、最後のフレーム画像を指定して拡張することができることがわかります。
## 非同期コールバック
Lumaがビデオを生成するのにかかる時間は比較的長く、約1〜2分かかります。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費するため、このAPIは非同期コールバックのサポートも提供しています。
全体の流れは次の通りです：クライアントがリクエストを発行する際に、追加で `callback_url` フィールドを指定します。クライアントが API リクエストを発行した後、API はすぐに結果を返し、現在のタスク ID を示す `task_id` フィールド情報を含みます。タスクが完了すると、生成された音楽の結果が POST JSON 形式でクライアントが指定した `callback_url` に送信され、その中にも `task_id` フィールドが含まれているため、タスクの結果を ID で関連付けることができます。
次に、具体的にどのように操作するかを例を通じて理解しましょう。
まず、Webhook コールバックは HTTP リクエストを受け取ることができるサービスであり、開発者は自分が構築した HTTP サーバーの URL に置き換える必要があります。ここではデモのために、公開の Webhook サンプルサイト [https://webhook.site/](https://webhook.site/) を使用します。このサイトを開くと、Webhook URL を取得できます。以下のように表示されます：
この URL をコピーすれば、Webhook として使用できます。このサンプルは [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13) です。
次に、フィールド `callback_url` を上記の Webhook URL に設定し、`prompt` を入力します。以下のように表示されます：
実行ボタンをクリックすると、すぐに結果が得られます。以下のようになります：
```json theme={null}
{
"task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6"
}
```
少し待つと、[https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13) で生成された曲の結果を観察できます。以下のように表示されます：
内容は以下の通りです：
```json theme={null}
{
"success": true,
"task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6",
"video_id": "4d8013c3-5de0-41aa-966e-0b1a51d1c633",
"prompt": "Astronauts shuttle from space to volcano",
"video_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.mp4",
"video_height": 752,
"video_width": 1360,
"state": "completed",
"thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.jpg",
"thumbnail_width": 1360,
"thumbnail_height": 752
}
```
結果には `task_id` フィールドがあり、他のフィールドは上記と似ているため、このフィールドを通じてタスクの関連付けが可能です。