> ## 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」按鈕，獲取請求所需要的憑證：

![](https://cdn.xhuoapi.ai/nyq0xz.png)

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請您來註冊和登錄，登錄註冊之後會自動返回當前頁面。

在首次申請時會有免費額度贈送，可以免費使用該 API。

## 基本使用

想要生成什麼視頻，可以任意輸入一段文字，比如我想生成一個關於宇航員穿梭於太空和火山之間的視頻，就可以輸入 `Astronauts shuttle from space to volcano`，如圖所示：

<p>
  <img src="https://cdn.xhuoapi.ai/yub02j.png" width="500" className="m-auto" />
</p>

生成的代碼如下：

<p>
  <img src="https://cdn.xhuoapi.ai/ieq7yn.png" width="500" className="m-auto" />
</p>

主要請求參數：

* `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` 字段可以傳入以下圖片作為視頻的首幀：

![首幀](https://cdn.xhuoapi.ai/r9vsv9.png)

接下來我們要根據首尾幀、關鍵詞自定義生成視頻，就可以指定如下內容：

* action：視頻生成任務的行為，通常是普通生成 `generate` 和擴展生成 `extend`，默認為 `generate`。
* start\_image\_url：指定生成視頻的首幀。
* end\_image\_url：指定生成視頻的尾幀。
* prompt：生成視頻的關鍵詞內容。

填寫樣例如下：

<p>
  <img src="https://cdn.xhuoapi.ai/zvzydx.png" width="500" className="m-auto" />
</p>

填寫完畢之後自動生成了代碼如下：

<p>
  <img src="https://cdn.xhuoapi.ai/tx80pu.png" width="500" className="m-auto" />
</p>

對應的代碼：

```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
}
```

最後得到的結果與上文的類似的，生成的視頻首幀包含了我們傳入的圖片，當然也可以同時傳入首尾幀圖片鏈接來生成視頻，只需要在上面的基礎上再加一個尾幀圖片即可，尾幀的圖片信息如下：

![尾幀](https://cdn.xhuoapi.ai/0iad3k.png)

填寫樣例如下：

<p>
  <img src="https://cdn.xhuoapi.ai/20igwi.png" width="500" className="m-auto" />
</p>

最後得出如下結果：

```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和視頻鏈接的獲取是根據基本使用來獲取，如下圖所示：

<p>
  <img src="https://cdn.xhuoapi.ai/fwknj4.png" width="500" className="m-auto" />
</p>

這時可以看到視頻的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：擴展生成視頻可指定尾幀的圖片鏈接，可選參數。

填寫樣例如下：

<p>
  <img src="https://cdn.xhuoapi.ai/vv0rxk.png" width="500" className="m-auto" />
</p>

填寫完畢之後自動生成了代碼如下：

<p>
  <img src="https://cdn.xhuoapi.ai/woapxi.png" width="500" className="m-auto" />
</p>

對應的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
}
```

可以看出該視頻是在需要擴展的視頻基礎上進行擴展的，結果內容與上文的是一致的，這也就實現歌曲的繼續生成功能。

當然我們也可以指定視頻的鏈接來進行擴展生成，填如下信息：

<p>
  <img src="https://cdn.xhuoapi.ai/0cv0hg.png" width="500" className="m-auto" />
</p>

運行後得到了如下結果：

```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
}
```

根據結果可以看出根據視頻鏈接也可以實現視頻擴展的功能。

最後我們還可以對擴展視頻中指定一個尾幀圖片來進行擴展，下面是尾幀圖片信息：

![尾幀](https://cdn.xhuoapi.ai/0iad3k.png)

接下來在上面的基礎上添加尾幀圖片信息，具體的如下所示：

<p>
  <img src="https://cdn.xhuoapi.ai/9p1vrj.png" width="500" className="m-auto" />
</p>

點擊運行後得到如下信息：

```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 會立馬返回一個結果，包含一個 `task_id` 的欄位資訊，代表當前的任務 ID。當任務完成之後，生成音樂的結果會通過 POST JSON 的形式發送到客戶端指定的 `callback_url`，其中也包括了 `task_id` 欄位，這樣任務結果就可以通過 ID 關聯起來了。

下面我們通過示例來了解下具體怎樣操作。

首先，Webhook 回調是一個可以接收 HTTP 請求的服務，開發者應該替換為自己搭建的 HTTP 伺服器的 URL。此處為了方便演示，使用一個公開的 Webhook 樣例網站 [https://webhook.site/，打開該網站即可得到一個](https://webhook.site/，打開該網站即可得到一個) Webhook URL，如圖所示：

<p>
  <img src="https://cdn.xhuoapi.ai/q78okf.png" width="500" className="m-auto" />
</p>

將此 URL 複製下來，就可以作為 Webhook 來使用，此處的樣例為 [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13。](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13。)

接下來，我們可以設置欄位 `callback_url` 為上述 Webhook URL，同時填入 `prompt`，如圖所示：

<p>
  <img src="https://cdn.xhuoapi.ai/n2fjvi.png" width="500" className="m-auto" />
</p>

點擊運行，可以發現會立即得到一個結果，如下：

```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) 上觀察到生成歌曲的結果，如圖所示：

![](https://cdn.xhuoapi.ai/1hwm5m.png)

內容如下：

```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` 欄位，其他的欄位都和上文類似，通過該欄位即可實現任務的關聯。