一、前提条件
·已 注册腾讯云 账号并开通 TokenHub 服务。
·已在 TokenHub 控制台 获取 API Key。
注意：说明：
注意：下文所有示例中的 YOUR_API_KEY 均需替换为你自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。
二、调用流程
图片生成为耗时任务，接口采用异步调用模式，统一分两步：
1. 提交任务：调用图片生成接口，成功返回 task_id。
2. 轮询结果：携带 task_id 调用 查询任务结果 接口，直至 status = completed，从结果中获取图片地址。
三、模型列表
注意：说明：
注意：WAND-Vega 生图模型提供 Lite、Flash、Pro 三档能力模型，支持文生图与参考生图。其中，Lite、Flash 档输入图片全部免费；Pro 档前 3 张输入图片免费，第 4 张起按张收取输入图片费用。
| 模型名称 | model 参数值 | 支持能力 | 提示词上限 | 分辨率 | 画面宽高比 |
| WAND-Vega-Image-1.0-Lite | wand-vega-image-lite | 文生图/参考生图 | 8192 字符 | 1K / 2K / 4K | 支持 1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9 常见尺寸 |
| WAND-Vega-Image-1.0-Flash | wand-vega-image-flash | 文生图/参考生图 | 8192 字符 | 1K / 2K / 4K | |
| WAND-Vega-Image-1.0-Pro | wand-vega-image-pro | 文生图/参考生图 | 8192 字符 | 1K / 2K / 4K | |
| WAND-Vega-Image-1.5-Pro | wand-vega-image-1.5-pro | 文生图/参考生图 | 8192 字符 | 1K / 2K / 4K | |
四、1. 接口描述
WAND-Vega 图片生成接口支持文生图、参考生图：以输入参考图+文本提示词生成图片，未传图片时按文本进行文生图。
接口：POST https://tokenhub.tencentmaas.com/v1/wand/vega-images/generations
五、2. 输入参数
| 参数名 | 必选 | 类型 | 描述 |
| model | 是 | string | 模型 ID。取值：wand-vega-image-litewand-vega-image-flashwand-vega-image-prowand-vega-image-1.5-pro |
| prompt | 是 | string | 文本提示词，长度 ≤ 8192 字符。未传 images 时按此文本进行文生图。 |
| input | 否 | array[object] | 多模态输入内容数组，用于图生图 / 参考图场景。 |
| input.content | 否 | array[object] | 输入内容片段数组，按顺序拼接为多模态提示。 |
| input.content.type | 否 | string | 内容类型，取值 input_image（参考图片）。 |
| input.content.image_url | 否 | string | 参考图片地址。最多支持10张。格式 png/jpeg。大小不超过20MB。 |
| size | 否 | string | 输出图片尺寸，格式 ${宽}x${高}。 |
六、3. 请求示例
文生图
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vega-images/generations' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "wand-vega-image-lite", "prompt": "A detailed painting of a butterfly", "size": "1024×1024"}'
参考生图
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vega-images/generations' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "wand-vega-image-lite", "prompt": "A seamless composition of all reference images", "input": [ { "content": [ { "type": "input_image", "image_url": "https://example.com/reference.jpg" } ] } ], "size": "1024×1024"}'
七、4. 输出参数
| 参数名 | 类型 | 描述 |
| task_id | string | WAND-Vega 生图生成的任务 ID，用于后续查询任务与回调匹配。 |
| request_id | string | 唯一请求标识，用于排查问题。 |
八、5. 响应示例
{ "task_id":"251380669-VegaImage-f91e7435e1e34dfa9898a451946bb3d3", "request_id":"5b7c57a3-e5e4-4df0-958b-e72d35582be1"}
九、1. 接口描述
查询图片生成任务的状态与结果。提交任务返回 task_id 后，通过本接口轮询获取结果。
接口：GET https://tokenhub.tencentmaas.com/v1/wand/vega-images/tasks/<task_id>
注意：说明：
注意：路径中的 {task_id} 即提交任务时返回的 task_id（示例中以 YOUR_TASK_ID 占位）。图片生成约需数秒至数十秒，建议每 3~5 秒轮询一次。
十、2. 输入参数
| 参数名 | 必选 | 类型 | 描述 |
| task_id | 是 | string | 任务 ID（路径参数），即提交任务时返回的 task_id。 |
十一、3. 请求示例
curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/vega-images/tasks/<task_id>' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json'
十二、4. 输出参数
| 字段 | 类型 | 说明 |
| status | string | 处理状态：queued/in_progress/completed/failed/cancelled/incomplete。queued：任务已接受，排队等待执行。in_progress：任务正在处理中。completed: 任务成功完成，可读取 data[].url 获取生成图片。failed: 任务执行失败。cancelled: 任务已被取消。incomplete: 任务被中断/未完成（如达到 token 上限） |
| request_id | string | 唯一请求标识，用于排查问题。 |
| data | array[object] | 生成结果列表。 |
| data[].url | string | 生成图片的下载地址，临时地址（含签名），请及时下载转存。 |
| usage | object | 用量消耗。 |
| usage.total_tokens | integer | 本次任务消耗的 token 数，用于计费/对账。 |
| created_at | string | 任务创建时间。 |
| finished_at | string | 任务完成时间。 |
十三、5. 响应示例
{ "task_id": "251380669-VegaImage-68a067d14b3c43c0961ce83373709f44", "status": "completed", "request_id": "92aa30e9-7549-4319-a0eb-467302d446f5", "data": [ { "url": "https://aigc-image.cos.myqcloud.com/xxx/result.png" } ], "usage": { "total_tokens": 16200 }, "created_at": 1787560807, "finished_at": 1787560820}
十四、错误码
请参见 API 错误码说明。