跳到内容

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-q21080p / 2K / 4K16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto最多 7 张

调用流程 ​

图片生成属于耗时任务,因此 API 采用异步调用方式,由以下两个步骤组成。

  1. 提交任务:调用图片生成 API。成功后会返回 task_id 和初始状态 created。
  2. 轮询结果:用 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)。回调正文与任务查询响应正文相同,通过回调签名算法进行认证。

请求示例 ​

基于参考图生成

bash
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)

bash
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_idstringVidu 生成的任务 ID,用于后续任务查询和回调匹配确认。
statestring处理状态:created / queueing / processing / success / failed。
promptstring本次调用的提示词参数。
created_atstring任务创建时间(ISO 8601)。
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

json
{
  "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(路径参数)。

请求示例 ​

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应参数 ​

字段类型说明
statestring处理状态:created / queueing / processing / success / failed。
modelstring本次调用使用的模型名称。
aspect_ratiostring本次调用的画面比例参数。
resolutionstring本次调用的分辨率参数。
creationsarray[object]生成结果列表,成功时返回。
creations[].urlstring生成图片的下载 URL 是有效期为 12 小时 的临时地址。请立即下载并保存。
request_idstring用于排查问题的唯一请求标识符。
tokenhub_usageobject用量。
tokenhub_usage.total_tokensinteger本次任务消耗的 token 数,用于计费/结算。

响应示例 ​

生成成功:

json
{
  "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 表示输出画面比例与第一张输入图片保持一致。该设置仅在参考图生图模式下有意义。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages