Vega Image
本模型需要白名单登记。
适用对象: WAND-Vega-Image 1.0 Pro。Lite 与 Flash 无需白名单登记即可使用。
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations认证: Tokenhub API Key / Bearer
Vega Image 是 WAND 自研的图片生成模型,可用文本生成图片,或基于参考图进行编辑。提供 1.0 Pro / 1.0 Flash / 1.0 Lite,请求后用任务 ID 查询结果。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| Pro 模型 ID | wand-vega-image-pro |
| Flash 模型 ID | wand-vega-image-flash |
| Lite 模型 ID | wand-vega-image-lite |
| 护栏解除支持 | 支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 参考图片 |
|---|---|---|---|
wand-vega-image-pro | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | 最多 10 张 |
wand-vega-image-flash | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | 最多 10 张 |
wand-vega-image-lite | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | 最多 10 张 |
Lite 与 Flash 没有参考图片的输入费用。1.0 Pro 前 3 张 免费,从第 4 张图片开始收取输入费用。
参考图片规格
| 版本 | 参考图片数 | 建议单文件容量 | 格式 |
|---|---|---|---|
wand-vega-image-pro | 最多 10 张 | 20MB 以下 | PNG / JPEG |
wand-vega-image-flash | 最多 10 张 | 20MB 以下 | PNG / JPEG |
wand-vega-image-lite | 最多 10 张 | 20MB 以下 | PNG / JPEG |
参考图片传入 input.content.image_url。输入请按单文件 20MB 以下来构成,图片数量以整个参考数组为基准计算。参考 URL 必须能被生成服务下载,非公开对象请使用有效的签名 URL。
Tokenhub 用一个 model 指定版本。在 VOD/MPS 中,ModelName=wand-vega-image 与 ModelVersion=1.0-pro / 1.0-flash / 1.0-lite 是分开传入的。
调用流程
图片生成是耗时较长的任务,因此 API 采用由以下两个阶段构成的异步调用方式。
- 提交任务: 调用图片生成 API。成功后会返回
task_id。 - 轮询结果: 在变为
status = completed之前,使用 task_id 调用任务结果查询API,然后从结果中获取图片 URL。
图片生成
API 说明
WAND-Vega 图片生成 API 支持基于文本的图片生成与基于参考图片的生成。它基于输入的参考图片与文本提示词生成图片;若未提供图片,则执行基于文本的图片生成。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型 ID。wand-vega-image-pro / wand-vega-image-flash / wand-vega-image-lite |
| prompt | 必填 | string | 文本提示词,长度须在 2000 字以内。若没有参考图片,则基于这段文本生成图片。 |
| input | 可选 | array[object] | 用于图片转换/参考图片场景的多模态输入内容数组。 |
| input.content | 可选 | array[object] | 输入内容片段数组。按顺序拼接,构成多模态提示词。 |
| input.content.type | 可选 | string | 内容类型。取值: input_image(参考图片)。 |
| input.content.image_url | 可选 | string | 参考图片 URL。各版本的张数、单文件容量及格式请查看参考图片规格。 |
| size | 可选 | string | ${width}x${height} 格式的输出图片尺寸。 |
请求示例
基于文本的图片生成
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "wand-vega-image-pro",
"prompt": "A detailed painting of a butterfly",
"size": "1024x1024"
}'基于参考图片的生成
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "wand-vega-image-pro",
"prompt": "A seamless composition of all reference images",
"input": [
{
"content": [
{
"type": "input_image",
"image_url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
}
]
}
],
"size": "1024x1024"
}'响应参数
| 参数 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务 ID。用于结果查询与回调关联。 |
| request_id | string | 用于排查问题的唯一请求标识。 |
响应示例
{
"task_id": "251380669-VegaImage-f91e7435e1e34dfa9898a451946bb3d3",
"request_id": "5b7c57a3-e5e4-4df0-958b-e72d35582be1"
}任务结果查询
查询路径
查询图片生成任务的状态与结果。提交任务并拿到 task_id 后,轮询这个 API 以获取结果。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/tasks/<task_id>
用提交任务时返回的 task_id,以 3~5 秒 的间隔查询。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 提交任务时返回的 task_id 任务 ID(路径参数)。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/tasks/<task_id>' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
status | String | 任务状态。参考下文的各状态处理 |
| request_id | string | 用于排查问题的唯一请求标识。 |
| data | array[object] | 生成的结果列表。 |
| data[].url | string | 生成图片的下载 URL。这是含签名的临时 URL,请在有效期内下载并保存。 |
| usage | object | 用量。 |
| usage.total_tokens | integer | 本任务消耗的令牌数,用于计费/结算。 |
| created_at | integer | 任务创建时刻。Unix timestamp(秒)。 |
| finished_at | integer | 任务完成时刻。Unix timestamp(秒)。 |
各状态的处理
| 状态 | 含义 | 处理 |
|---|---|---|
queued | 等待生成 | 继续查询状态 |
in_progress | 生成中 | 继续查询状态 |
completed | 生成完成 | 从 data.url 下载图片 |
failed | 生成失败 | 确认错误响应 |
cancelled | 已取消 | 结束查询 |
incomplete | 以未完成状态结束 | 确认结束原因 |
响应示例
{
"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
}参考输入与结果地址
请在 input.content.image_url 中传入可下载的原始图片 URL。图片参考输入与素材库登记是两回事。
生成结果从 data.url 获取。返回的 COS 下载 URL 要使用含查询字符串的完整地址,并请在过期前保存文件。图片生成结果的 URL 与视频用的 asset://<id> 是不同的值。
输出尺寸
size 是请求尺寸。Flash 即便在基于文本的生成中,也可能返回与请求不同尺寸·比例的图片。保存前请确认结果文件的实际宽·高与宽高比。
各比例的像素规格
| 比例 | 1K 分辨率 | 2K 分辨率 | 4K 分辨率 |
|---|---|---|---|
1:1 | 1024×1024 / 1080×1080 | 2048×2048 / 2160×2160 | 4096×4096 |
2:3 | 1024×1536 / 1080×1620 | 1440×2160 | 3328×4992 |
3:2 | 1536×1024 / 1620×1080 | 2160×1440 | 4992×3328 |
3:4 | 1080×1440 | 1440×1920 / 2160×2880 | 3584×4800 |
4:3 | 1440×1080 | 1920×1440 / 2880×2160 | 4800×3584 |
9:16 | 720×1280 / 1080×1920 | 1440×2560 | 2160×3840 |
16:9 | 1280×720 / 1920×1080 | 2560×1440 | 3840×2160 |
21:9 | 1512×648 | 2520×1080 | 5040×2160 |
错误码
请参考 API 错误码。