Luma API 的使用

Luma 是一个专注于高质量视频生成的平台，用户只需上传素材，即可根据不同的风格和效果自动生成高质量的视频。该 AI 视频生成器是由来自知名科技公司的团队开发，旨在让每个人在不使用复杂编辑工具的情况下，轻松制作优秀的视频。

然而，Luma 官方并未提供 API。AceDataCloud 提供了一套 Luma 的 API，模拟了与 Suno 官方的对接，使得生成所需视频变得方便快捷。

申请和使用

使用 Luma Videos API 前，首先请访问 Ace Data Cloud 页面，点击「Acquire」按钮以获取请求所需的凭证：

如果您尚未登录或注册，会自动跳转到登录页面，邀请您进行注册或登录，完成登录或注册后会自动返回到当前页面。

首次申请时，您将获得免费的额度，可以免费使用该 API。

基本使用

想要生成视频时，可以输入任何一段文字。例如，如果我想生成一个关于宇航员在太空和火山之间穿梭的视频，可以输入 Astronauts shuttle from space to volcano，如下图所示：

生成的代码如下：

您可以点击「Try」按钮直接测试 API，稍等 1-2 分钟，结果如下：

json { "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.acedata.cloud/luma/e4018a99-1522-4f24-9330-62c2a9b50b59.jpg", "thumbnail_width": 1360, "thumbnail_height": 752 }

可以看到此时我们得到了该视频的相关信息，包括视频 ID、视频链接和视频封面等信息。

字段说明如下：

success：表示生成是否成功，成功则为 true，否则为 false
task_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 import requests

url = "https://api.acedata.cloud/luma/videos"

headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }

payload = { "start_image_url": "https://cdn.zhishuyun.com/0b3b2e88-eaf4-441f-b032-eb580642a140.png", "action": "generate", "prompt": "Astronauts shuttle from space to volcano" }

response = requests.post(url, json=payload, headers=headers) print(response.text) ```

得到的结果如下：

json { "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.acedata.cloud/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 }

最后得到的结果与之前的类似，生成的视频首帧包含了我们输入的图片。当然，也可以同时传入首尾帧的图片链接来生成视频，只需在上述基础上再添加一个尾帧图片即可，尾帧的图片信息如下：

填写样例如下：

最后得出如下结果：

json { "success": true, "task_id": "d1cb723a-e554-4775-94a4-bb6ae8c7ea67", "video_id": "6bebd0d2-f793-472e-9326-38528a9273bb", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.acedata.cloud/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/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.acedata.cloud/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 import requests

url = "https://api.acedata.cloud/luma/videos"

headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }

payload = { "action": "extend", "video_id": "0105c090-03a5-425a-8026-523341cd575b", "prompt": "Astronauts shuttle from space to volcano" }

response = requests.post(url, json=payload, headers=headers) print(response.text) ```

点击运行后，可以发现得到的结果如下：

json { "success": true, "task_id": "c6e529d1-a06d-4c12-91b2-c855135131c3", "video_id": "36908c49-c2bb-4a11-bd5a-b8512b004818", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.acedata.cloud/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 }

可以看到该视频是在需要扩展的视频基础上进行扩展的，结果内容与上文一致，从而实现了视频的继续生成功能。

当然，我们也可以指定视频链接来进行扩展生成，具体填写信息如下：

运行后得到的结果如下：

json { "success": true, "task_id": "1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca", "video_id": "f0187dc2-339f-4a08-a435-c3a3341f620a", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.acedata.cloud/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 }

根据结果可以看到，通过视频链接也可以实现视频扩展功能。

最后，我们还可以在扩展视频中指定尾帧图片，以下是尾帧图片信息：

接下来，在上面的基础上添加尾帧图片信息，具体如下所示：

点击运行后得到的信息如下：

json { "success": true, "task_id": "b816b2b4-c345-4673-9e19-83e91f91b643", "video_id": "c5400053-63e6-4206-8082-31cf9dd1e7ed", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.acedata.cloud/luma/b816b2b4-c345-4673-9e19-83e91f91b643.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/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/，打开该网站可获得一个 Webhook URL，如下图所示：

将此 URL 复制后，即可作为 Webhook 使用，此处的示例为 https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13。

接下去，我们可以将字段 callback_url 设置为上述 Webhook URL，同时填写 prompt，如图所示：

点击运行后，您会立即看到结果，如下：

json { "task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6" }

等待片刻，我们可以在 https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13 上查看生成视频的结果，如图所示：

内容如下：

json { "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.acedata.cloud/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.mp4", "video_height": 752, "video_width": 1360, "state": "completed", "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.jpg", "thumbnail_width": 1360, "thumbnail_height": 752 }

结果中包含一个 task_id 字段，其他字段与上文类似，通过该字段便可实现任务的关联。