Vidu
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation认证: Tokenhub API Key / Bearer
Vidu Image q2 是图片生成模型,支持文生图、参考图生图(0~7 张)和图片编辑。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 支持解除护栏 | 支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 参考图 |
|---|---|---|---|
vidu-image-q2 | 1080p / 2K / 4K | 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto | 最多 7 张 |
调用流程
图片生成属于耗时任务,因此 API 采用异步调用方式,由以下两个步骤组成。
- 提交任务:调用图片生成 API。成功后会返回
task_id和初始状态created。 - 轮询结果:用
task_id调用任务结果查询 API,直到状态变为state = success,再从结果中获取图片 URL。通过callback_url配置回调后,可以让服务器在任务状态变更时发送通知。
参考: 任务状态:created(创建完成)/ queueing(排队中)/ processing(处理中)/ success(成功)/ failed(失败)。所有 API 响应中都包含用于排查问题的顶层 request_id。查询 API 还会返回表示用量的 usage。
图片生成
API 说明
Vidu 图片生成(基于参考图生成)API 支持基于参考图生成、文生图以及图片编辑。可以用参考图 0~7 个 和文本提示词生成图片,也可以不提供参考图、仅做文生图。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型 ID。取值:vidu-image-q2 |
| prompt | 必填 | string | 文本提示词,最大长度为 2000 个字符。不传 images 时,将基于该文本执行文生图。 |
| images | 选填 | array[string] | 参考图 0~7 张。支持图片 URL 或 Base64,Base64 需要带 data:image/png;base64, 前缀。格式:png/jpeg/jpg/webp。像素尺寸:128×128 以上。画面比例:必须小于 1:4 或大于 4:1。单张图片 1 个 最大 50 MB,POST 正文最大 20 MB。 |
| aspect_ratio | 选填 | string | 画面比例。可选项:16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto(与第一张输入图片的画面比例相同)。默认值:16:9。 |
| resolution | 选填 | string | 分辨率。可选项:1080p / 2K / 4K。默认值:1080p。 |
| seed | 选填 | integer | 随机种子。不指定或设为 0 时使用随机数。 |
| callback_url | 选填 | string | 任务状态变更回调 URL(POST)。回调正文与任务查询响应正文相同,通过回调签名算法进行认证。 |
请求示例
基于参考图生成
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "vidu-image-q2",
"images": [
"https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
],
"prompt": "a cat sitting on a windowsill at sunset",
"aspect_ratio": "16:9",
"resolution": "2K"
}'文生图(无 images)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "vidu-image-q2",
"prompt": "a cat sitting on a windowsill at sunset",
"aspect_ratio": "16:9",
"resolution": "1080p"
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | Vidu 生成的任务 ID,用于后续任务查询和回调匹配确认。 |
| state | string | 处理状态:created / queueing / processing / success / failed。 |
| prompt | string | 本次调用的提示词参数。 |
| created_at | string | 任务创建时间(ISO 8601)。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
{
"task_id": "1374200352-WandImage-a457a7b042694f8aad4deeff8c7f7ef3",
"state": "created",
"prompt": "a cat sitting on a windowsill at sunset",
"created_at": "2026-08-20T07:31:07.277Z",
"request_id": "26eb0d62-1c52-4f3a-9b5e-7e8fb2524d8f"
}错误码
请求失败时会返回错误码。详细内容请参考 ErrMsg/错误信息。常见错误码请参考 附录:统一错误码。
查询任务结果
API 说明
查询图片生成任务的状态和结果。提交任务并返回 task_id 后,轮询该 API 以获取结果。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/{task_id}
参考: 路径中的 {task_id} 是提交任务时返回的 task_id,示例中以 YOUR_TASK_ID 表示。图片生成大约需要数秒到数十秒,建议每 3~5 秒 轮询一次。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 提交任务时返回的 task_id 任务 ID(路径参数)。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| state | string | 处理状态:created / queueing / processing / success / failed。 |
| model | string | 本次调用使用的模型名称。 |
| aspect_ratio | string | 本次调用的画面比例参数。 |
| resolution | string | 本次调用的分辨率参数。 |
| creations | array[object] | 生成结果列表,成功时返回。 |
| creations[].url | string | 生成图片的下载 URL 是有效期为 12 小时 的临时地址。请立即下载并保存。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
| tokenhub_usage | object | 用量。 |
| tokenhub_usage.total_tokens | integer | 本次任务消耗的 token 数,用于计费/结算。 |
响应示例
生成成功:
{
"state": "success",
"model": "vidu-image-q2",
"prompt": "a cat sitting on a windowsill at sunset",
"creations": [
{
"url": "https://aigc-image.cos.myqcloud.com/xxx/result.png"
}
],
"aspect_ratio": "16:9",
"resolution": "2K",
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2",
"tokenhub_usage": {
"total_tokens": 1024
}
}错误码
| state | 说明 | 建议处理方式 |
|---|---|---|
| success | 生成成功 | 从 creations.url 获取结果图片。 |
| processing / queueing | 处理中/排队中 | 每 3~5 秒 轮询一次,直到状态变为 success。 |
| failed | 生成失败 | 确认失败原因并修正后重试。若持续失败,请联系技术支持并提供 request_id。 |
请求级错误码请参考 附录:统一错误码。
附录
统一错误码
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| BadRequest | 请求有误 | 无效请求 |
| FieldLacking | 字段缺失或为空 | 缺少必填字段 |
| FieldUnwanted | 不需要的字段 | 传入了不允许的字段。 |
| FieldInvalid | 无效字段 | 输入参数未通过校验。 |
| FieldItemCountOutOfRange | 字段项数超出范围 | 字段项数超过限制(例如图片数量超过限制)。 |
| PageSizeOutOfRange | 页面大小超出范围 | 图片尺寸/参数超过限制。 |
| ImageFormatInvalid | 无效的图片格式 | 图片格式不满足要求。 |
| ImageSizeInvalid | 无效的图片尺寸 | 图片尺寸过大或过小。 |
| ImageDownloadFailure | 图片下载失败 | 未能从 URL 下载图片。请确认链接。 |
| TaskPromptPolicyViolation | 提示词违反策略 | 提示词触发了安全审核和风险控制。 |
| CreationPolicyViolation | 生成内容违反策略 | 生成的内容触发了风险控制。 |
| AuditSubmitIllegal | 提交无效 | 输入未通过安全审核。 |
| CreditInsufficient | 额度不足 | 额度不足。 |
| ModelUnavailable | 模型不可用 | 模型无法使用。 |
| Unauthorized | 未认证 | 未通过认证(请确认 Authorization)。 |
| Forbidden | 被禁止 | 没有请求权限。 |
| TaskNotFound | 未找到任务 | 未找到 task_id。 |
| QuotaExceeded | 配额超限 | 超过并发执行限制。 |
| TooManyRequests | 请求过多 | 请求频率过高。 |
| InternalServiceFailure | 内部服务错误 | 内部服务器错误 |
图片素材通用限制
格式:png / jpeg / jpg / webp。分辨率:最小 128×128 像素。画面比例:必须小于 1:4 或大于 4:1。图片 1 个 大小:最大 50 MB。POST 正文大小:最大 20 MB。支持图片 URL 或 Base64,Base64 必须包含 data:image/png;base64, 前缀。
FAQ
1. 如何区分文生图和图生图?
同一个 API 同时支持两种模式。传入 images 时,会启用参考图片内参考对象的参考图生图;省略 images 时,则启用仅凭提示词生成的文生图。vidu-image-q2 同时支持这两种模式。
2. 生成的图片链接会过期吗?
生成结果是 12 小时 后过期的临时地址。任务成功后请立即从 creations.url 下载图片并保存到自有存储中。请勿长期使用该链接。
3. auto 画面比例是什么?
aspect_ratio: auto 表示输出画面比例与第一张输入图片保持一致。该设置仅在参考图生图模式下有意义。