Veo Videos Generation API 对接说明

本文介绍了如何对接 Veo Videos Generation API，通过输入自定义参数生成Veo官方视频。

下面将详细阐述 Veo Videos Generation API 的对接流程。

申请流程

使用 API 前，需前往 Veo Videos Generation API 页面申请服务。进入页面后，点击「Acquire」按钮，如下图所示：

如果尚未登录或注册，将自动跳转至登录页面，邀请您注册或登录。登录后将返回到当前页面。

首次申请时会获得免费额度，可免费使用该 API。

基本使用

基本使用方式为输入提示词 prompt、生成行为 action、首尾帧参考图片数组 image_urls 及模型 model 来获取处理结果。需首先传递 action 字段，值为 text2video，此字段包含三种行为：文生视频（text2video）、图生视频（image2video）、获取1080p视频（get_1080p）。接着需输入模型 model，当前可选择 veo2、veo2-fast、veo3 和 veo3-fast，具体内容如下：

可以看到设置了请求头部，包括：

• accept：希望收到的响应格式，此处填写为 application/json，即 JSON 格式。
• authorization：调用 API 需要的密钥，申请后可以直接下拉选择。

同时设置了请求主体，包括：

• model：生成视频时使用的模型，主要有 veo2、veo2-fast、veo3 和 veo3-fast。
• action：视频生成任务的行为，包括文生视频（text2video）、图生视频（image2video）、获取1080p视频（get_1080p）。
• image_urls：若选择图生视频行为 image2video，必须上传的首尾帧参考图片链接。
• prompt：提示词。
• callback_url：需要回调结果的 URL。

选择后，会自动生成对应的代码，如图所示：

点击「Try」按钮可进行测试，得到如下结果：

json { "success": true, "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11", "trace_id": "9906dac0-1516-41dc-9fe3-067ca1ba8269", "data": [ { "id": "253eedc47f1c4eb2a370ed2312168f4b", "video_url": "https://platform.cdn.acedata.cloud/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4", "created_at": "2025-07-25 16:07:43", "complete_at": "2025-07-25 16:10:28", "state": "succeeded" } ] }

返回的结果包括多个字段，具体如下：

• success：当前视频生成任务状态。
• task_id：当前视频生成任务的 ID。
• data：视频生成任务结果。
• id：视频生成任务的视频 ID。
• video_url：视频生成任务的视频链接。
• created_at：视频生成任务创建时间。
• complete_at：视频生成任务完成时间。
• state：视频生成任务状态。

收到满意的视频信息后，可以根据 data 中视频链接获取生成的Veo视频。

如果想生成对应的对接代码，可以直接复制，例如 CURL 的代码如下：

shell curl -X POST 'https://api.acedata.cloud/veo/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "veo2", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }'

图生视频功能

如果想根据首尾帧图片生成视频，需将参数 action 设置为 image2video，同时输入首尾帧图片链接数组 image_urls。

接下来必须填写提示词以自定义生成视频，可指定如下内容：

• model：生成视频的模型，主要有 veo2、veo2-fast、veo3 和 veo3-fast。
• image_urls：必须上传的首尾帧参考图片链接。
• prompt：提示词。

填写示例如下：

填写完成后自动生成的代码如下：

对应的 Python 代码为：

```python import requests

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

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

payload = { "action": "image2video", "model": "veo2", "prompt": "Let it dance", "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"] }

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

点击运行，可以得到如下结果：

json { "success": true, "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87", "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8", "data": [ { "id": "59f12222b1fa4fbe9331ff2400ad1583", "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4", "created_at": "2025-07-25 16:13:07", "complete_at": "2025-07-25 16:16:12", "state": "succeeded" } ] }

结果与前文一致，从而实现图生视频功能。

获取1080p视频功能

如需对已生成的视频获取1080p，可将参数 action 设置为 get_1080p，并输入需要获取1080p的视频 ID，视频 ID 可通过基本使用获取，如图所示：

此时视频的 ID 为：

json "id": "59f12222b1fa4fbe9331ff2400ad1583"

注意，此处的 video_id 是生成后视频的 ID，若不知如何生成视频，请参考前文基本使用生成视频。

接下来需填写提示词以自定义生成视频，可指定如下内容：

• model：生成视频的模型，主要有 veo2、veo2-fast、veo3 和 veo3-fast。
• video_id：参考的视频 ID，用于获取1080p视频。

填写示例如下：

填写完成后自动生成的代码如下：

点击运行后将得到如下结果：

json { "success": true, "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984", "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d", "data": [ { "id": "59f12222b1fa4fbe9331ff2400ad1583", "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4", "created_at": "2025-07-25 16:13:07", "complete_at": "2025-07-25 16:16:12", "state": "succeeded" } ] }

结果与前文一致，从而实现获取1080p视频功能。

指定视频尺寸生成

如需生成自定义尺寸的Veo视频，可将参数 aspect_ratio 设置为所需尺寸，接下来需填写提示词以自定义生成视频，可指定如下内容：

• model：生成视频的模型，主要有 veo2、veo2-fast、veo3 和 veo3-fast。
• aspect_ratio：视频尺寸，支持 16:9、3:4、4:3、1:1，默认值为 16:9。
• translation：是否启用提示词自动翻译，默认值为 false。

填写示例如下：

填写完成后将自动生成代码如下：

点击运行后将得到如下结果：

json { "success": true, "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687", "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886", "data": [ { "id": "fc667e7d3b8f44beaa61a3c339af0e50", "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4", "created_at": "2025-08-24 20:09:06", "complete_at": "2025-08-24 20:10:45", "state": "succeeded" } ] }

结果与前文一致，从而实现指定尺寸生成视频的功能。

异步回调

鉴于 Veo Videos Generation API 的生成时间较长，通常需要 1-2 分钟。如果 API 长时间没有响应，HTTP 请求将保持连接，导致系统资源消耗增加，因此本 API 提供了异步回调支持。

整体流程为：客户端发起请求时，额外指定 callback_url 字段。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/aed5cd28-f8aa-4dca-9480-8ec9b42137dc。

接下来，设置字段 callback_url 为上述 Webhook URL，并填写相应参数，具体内容如图所示：

点击运行，将立即得到如下结果：

json { "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed" }

稍等片刻，在 https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc 可以观察生成视频结果，如图所示：

内容如下：

json { "success": true, "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "data": [ { "id": "2f43ceed37944b4d836e1a1899dad0a1", "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4", "created_at": "2025-07-25 17:19:20", "complete_at": "2025-07-25 17:21:45", "state": "succeeded" } ] }

结果中带有一个 task_id 字段，其他字段与前文类似，通过此字段可实现任务关联。

错误处理

调用 API 时遇到错误，API 将返回相应的错误代码与信息，如：

• 400 token_mismatched：错误请求，可能因缺失或无效参数造成。
• 400 api_not_implemented：错误请求，可能因缺失或无效参数造成。
• 401 invalid_token：未经授权，无效或缺失授权令牌。
• 429 too_many_requests：请求过多，超出速率限制。
• 500 api_error：内部服务器错误，服务器出现问题。

错误响应示例

json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" }

结论

通过本文档，您已了解如何使用 Veo Videos Generation API，通过输入提示词及首帧参考图片生成视频。希望本文档能够帮助您更好地对接与使用该 API。如有任何疑问，请随时联系我们的技术支持团队。