Veo 3.1 API 接入文档

使用 VezAPI 密钥接入 Veo 3.1。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

扩展veo3.1视频

POST/api/v1/jobs/createTask

模型标识： veo/extend

参数	类型	说明与限制
`model` 必填	`string`	模型名称可选值：`"veo/extend"` 默认：`"veo/extend"`
`callBackUrl` 可选	`string`	任务完成时的回调URL（可选）。强烈推荐在生产环境中使用。 - 系统将在视频扩展完成时向此URL发送POST请求，包含任务状态和结果 - 回调包含生成的视频URL、任务信息等内容 - 您的回调端点应能接受包含视频结果的JSON载荷的POST请求 - 详细的回调格式和实现指南，请参见 [视频生成回调]([see VezAPI documentation]) - 也可轮询获取任务详情（/cn/market/common/get-task-detail）。 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`
`input.task_id` 必填	`string`	原始视频生成任务的ID。必须是从视频生成接口返回的有效taskId。
`input.prompt` 必填	`string`	描述扩展视频内容的文本提示词。应该详细描述您希望视频如何扩展，包括动作、场景变化、风格等。
`input.seeds` 可选	`integer`	随机种子参数，用于控制生成内容的随机性。取值范围为10000-99999。相同的种子会生成相似的视频内容，不同的种子会生成不同的视频内容。不填写时系统自动分配。 `minimum: 10000` `maximum: 99999`
`input.model` 可选	`string`	续写档位，"fast"（默认）、"quality"、"lite"，按所选档位每次计费。 - fast: 快速生成模式 - quality: 高质量生成模式 - lite: 最低成本模式可选值：`"fast", "quality", "lite"` 默认：`"fast"`
`input.watermark` 可选	`string`	水印文本（可选）。如果提供，将在生成的视频上添加水印。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "veo/extend",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "task_id": "veo_task_abcdef123456",
    "prompt": "The dog continues running through the park, jumping over obstacles and playing with other dogs",
    "seeds": 12345,
    "watermark": "MyBrand"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200, 400, 401, 402, 404, 422, 429, 455, 500, 501, 505`
`msg` 可选	`string`	响应消息
`data` 可选	`object`
`data.taskId` 可选	`string`	任务 ID，可用于[获取任务详情](/cn/market/common/get-task-detail)接口查询任务状态

HTTP 500

响应字段与业务状态码。

参数	类型	说明与限制
`code` 必填	`integer`	业务状态码：200 请求成功；401 鉴权凭据缺失或无效；402 积分不足；404 资源或接口不存在；408 超过 10 分钟未返回结果；422 参数校验失败；429 请求频率超限；455 系统维护；500 处理请求时发生内部错误；501 内容生成失败；505 功能当前关闭。
`msg` 必填	`string`	响应消息；失败时说明错误原因。
`data` 必填	`object`

生成veo3.1视频

POST/api/v1/jobs/createTask

模型标识： veo-3-1

参数	类型	说明与限制
`model` 必填	`string`	固定为 "veo-3-1"；选择 Fast / Lite / Quality 档位请用 input.model。可选值：`"veo-3-1"` 默认：`"veo-3-1"`
`callBackUrl` 可选	`string`	用于接收视频生成任务完成更新的URL地址。可选但推荐在生产环境中使用。 - 系统将在视频生成完成时向此URL发送POST请求，包含任务状态和结果 - 回调包含生成的视频URL、任务信息等内容 - 您的回调端点应能接受包含视频结果的JSON载荷的POST请求 - 详细的回调格式和实现指南，请参见 [视频生成回调](/cn/veo3-api/generate-veo-3-video-callbacks) - 也可轮询获取任务详情（/cn/market/common/get-task-detail）。 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`
`input.prompt` 必填	`string`	描述所需视频内容的文本提示词。所有生成模式都需要。 - 应该详细且具体地描述视频内容 - 可以包含动作、场景、风格等信息 - 对于图片生成视频，描述希望图片如何动起来
`input.model` 可选	`string`	Veo 3.1 档位，"veo3_fast"（默认）、"veo3_lite"、"veo3"（Quality）。顶层 model 固定为 "veo-3-1"。REFERENCE_2_VIDEO 支持 veo3_fast 与 veo3_lite。可选值：`"veo3_fast", "veo3_lite", "veo3"` 默认：`"veo3_fast"`
`input.image_urls` 可选	`array`	图片地址。首尾帧模式：1 张（首帧）或 2 张（首帧+尾帧）；参考图模式：1–3 张，仅支持 8 秒。
`input.generation_type` 可选	`string`	视频生成模式（可选）。指定不同的视频生成方式： - TEXT_2_VIDEO：文生视频 - 仅使用文本提示词生成视频 - FIRST_AND_LAST_FRAMES_2_VIDEO：首尾帧生视频 - 灵活的图片到视频生成模式 - 传1张图片：基于该图片生成视频 - 传2张图片：第一张作为首帧，第二张作为尾帧，生成过渡视频 - REFERENCE_2_VIDEO：参考图生视频 - 基于参考图片生成视频，需要在 image_urls 中提供1-3张图片（至少1张，最多3张）重要提示： - REFERENCE_2_VIDEO 模式目前支持 veo3_fast 和 veo3_lite 模型 - 不填写时系统会根据是否提供 image_urls 自动判断生成模式可选值：`"TEXT_2_VIDEO", "FIRST_AND_LAST_FRAMES_2_VIDEO", "REFERENCE_2_VIDEO"`
`input.watermark` 可选	`string`	水印文本。 - 可选参数 - 如果提供，将在生成的视频上添加水印
`input.aspect_ratio` 可选	`string`	视频的宽高比。用于指定生成视频的尺寸比例。可选值： - 16:9：横屏视频格式。 - 9:16：竖屏视频格式，适合移动端短视频 - Auto：自动模式，视频会根据上传图片更接近16:9还是9:16自动进行居中裁剪。默认值为 16:9。可选值：`"16:9", "9:16", "Auto"` 默认：`"16:9"`
`input.enable_fallback` 可选	`boolean`	已废弃，请从请求中移除。默认：`false`
`input.enable_translation` 可选	`boolean`	可选。为 true 时先把提示词翻译成英文再生成。
`input.resolution` 可选	`string`	输出分辨率：720p（默认）、1080p、4k。1080p 与 4k 的视频地址在 resultJson.data.result_urls（720p 版本在 data.origin_urls）。控制生成视频的像素尺寸。较高的分辨率带来更高的清晰度和细节表现，而较低的分辨率则能实现更快的生成速度。可选值：`"720p", "1080p", "4k"` 默认：`"720p"`
`input.duration` 可选	`integer`	生成视频的时长，单位为秒。可选值为 4、6、8。重要提示： - REFERENCE_2_VIDEO 模式目前仅支持8s。可选值：`4, 6, 8` 默认：`8`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "veo-3-1",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "A dog playing in a park",
    "image_urls": [
      "https://example.com/input.png",
      "https://example.com/input.png"
    ],
    "watermark": "MyBrand",
    "aspect_ratio": "16:9",
    "enable_translation": true,
    "generation_type": "REFERENCE_2_VIDEO"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200, 400, 401, 402, 404, 422, 429, 455, 500, 501, 505`
`msg` 可选	`string`	响应消息
`data` 可选	`object`
`data.taskId` 可选	`string`	任务 ID，可用于[获取任务详情](/cn/market/common/get-task-detail)接口查询任务状态

HTTP 500

服务器错误

获取1080P视频

POST/api/v1/jobs/createTask

模型标识： veo/get-1080p-video

参数	类型	说明与限制
`model` 必填	`string`	模型名称；此处的固定值为 veo/get-1080p-video。
`callBackUrl` 可选	`string`	任务完成通知的回调 URL。可选参数。如果提供，系统将在任务完成（无论成功还是失败）时向此 URL 发送 POST 请求。如果省略，则不会发送回调通知。
`input` 必填	`object`
`input.taskId` 必填	`string`	任务ID
`input.index` 可选	`string`	视频索引

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "veo/get-1080p-video",
  "input": {
    "taskId": "Your prompt"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。taskId 不存在或原任务失败时返回非 200 的 code，重试无效。可选值：`200, 401, 404, 422, 429, 451, 455, 500`
`msg` 可选	`string`	响应消息
`data` 可选	`object`
`data.resultUrl` 可选	`string`	1080P高清视频下载地址

HTTP 500

服务器错误

获取4K视频

POST/api/v1/jobs/createTask

模型标识： veo/get-4k-video

参数	类型	说明与限制
`model` 必填	`string`	模型名称默认：`"veo/get-4k-video"`
`callBackUrl` 可选	`string`	用于接收4K视频生成任务完成更新的URL地址。可选但推荐在生产环境中使用。 - 系统将在4K视频生成完成时向此URL发送POST请求，包含任务状态和结果 - 回调包含生成的视频URL、媒体ID等内容 - 您的回调端点应能接受包含结果的JSON载荷的POST请求 - 也可轮询获取任务详情（/cn/market/common/get-task-detail）。 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`
`input.task_id` 必填	`string`	任务ID
`input.index` 可选	`integer`	视频索引默认：`0`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "veo/get-4k-video",
  "input": {
    "task_id": "veo_task_abcdef123456"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。taskId 不存在或原任务失败时返回非 200 的 code，重试无效。可选值：`200, 401, 404, 422, 429, 451, 455, 500`
`msg` 可选	`string`	响应消息
`data` 可选	`object`
`data.taskId` 可选	`string`	任务 ID，可用于[获取任务详情](/cn/market/common/get-task-detail)接口查询任务状态
`data.resultUrls` 可选	`array`	Generated 4K video URLs
`data.imageUrls` 可选	`array`	Related thumbnail or preview image URLs

HTTP 500

服务器错误

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。