Vega Image โ
This model requires allowlist registration.
Applies to: WAND-Vega-Image 1.0 Pro. Lite and Flash are available without allowlist registration.
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generationsAuthentication: Tokenhub API Key / Bearer
Vega Image is WAND's in-house image generation model; it generates images from text or edits reference images. It offers 1.0 Pro / 1.0 Flash / 1.0 Lite, and you query the result by task ID after the request.
Basic information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Pro model ID | wand-vega-image-pro |
| Flash model ID | wand-vega-image-flash |
| Lite model ID | wand-vega-image-lite |
| Guardrail bypass support | Supported |
Supported specs by version โ
| Version | Resolution | Ratio | Reference images |
|---|---|---|---|
wand-vega-image-pro | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | Up to 10 |
wand-vega-image-flash | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | Up to 10 |
wand-vega-image-lite | 1K / 2K / 4K | 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9 | Up to 10 |
Lite and Flash have no input cost for reference images. On 1.0 Pro the first 3 are free, and input costs apply starting from the 4th image.
Reference image specs โ
| Version | Number of reference images | Recommended size per file | Formats |
|---|---|---|---|
wand-vega-image-pro | Up to 10 | 20MB or less | PNG / JPEG |
wand-vega-image-flash | Up to 10 | 20MB or less | PNG / JPEG |
wand-vega-image-lite | Up to 10 | 20MB or less | PNG / JPEG |
Reference images are passed in input.content.image_url. Keep each input file at 20MB or less, and the image count is calculated against the entire reference array. Reference URLs must be downloadable by the generation service; for private objects, use a valid signed URL.
Tokenhub specifies the version with a single model. In VOD/MPS, ModelName=wand-vega-image and ModelVersion=1.0-pro / 1.0-flash / 1.0-lite are passed separately.
Call procedure โ
Image generation is a long-running task, so API uses an asynchronous call pattern made up of the following two stages.
- Submit the task: Call the image generation API. On success,
task_idis returned. - Poll for the result: Until it becomes
status = completed, call thetask result queryAPI using task_id, then take the image URL from the result.
Image generation โ
API overview โ
The WAND-Vega image generation API supports text-based image generation and reference-image-based generation. It generates an image based on the reference images and text prompt you provide; if no image is provided, it performs text-based image generation.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/generations
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model ID. wand-vega-image-pro / wand-vega-image-flash / wand-vega-image-lite |
| prompt | Required | string | The text prompt; its length must be 2000 characters or fewer. If there is no reference image, the image is generated based on this text. |
| input | Optional | array[object] | The multimodal input content array used in image-transform / reference-image scenarios. |
| input.content | Optional | array[object] | An array of input content segments. They are concatenated in order to compose a multimodal prompt. |
| input.content.type | Optional | string | Content type. Value: input_image (reference image). |
| input.content.image_url | Optional | string | Reference image URL. For the per-version count, per-file size, and formats, check the reference image specs. |
| size | Optional | string | The output image size in ${width}x${height} format. |
Request examples โ
Text-based image generation
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"
}'Reference-image-based generation
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"
}'Response parameters โ
| Parameter | Type | Description |
|---|---|---|
| task_id | string | The task ID. Used for result queries and callback correlation. |
| request_id | string | A unique request identifier used for troubleshooting. |
Response example โ
{
"task_id": "251380669-VegaImage-f91e7435e1e34dfa9898a451946bb3d3",
"request_id": "5b7c57a3-e5e4-4df0-958b-e72d35582be1"
}Querying task results โ
Query path โ
Queries the status and result of an image generation task. After submitting the task and receiving task_id, poll this API to get the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-images/tasks/<task_id>
Query at 3~5 seconds intervals using the task_id returned when the task was submitted.
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task_id task ID returned when the task was submitted (a path parameter). |
Request example โ
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'Response parameters โ
| Field | Type | Description |
|---|---|---|
status | String | Task status. See the handling by status below |
| request_id | string | A unique request identifier used for troubleshooting. |
| data | array[object] | The list of generated results. |
| data[].url | string | The download URL of the generated image. It is a temporary URL that includes a signature, so download and save it within its validity period. |
| usage | object | Usage. |
| usage.total_tokens | integer | The number of tokens consumed by this task, used for billing and settlement. |
| created_at | integer | The time the task was created. Unix timestamp (seconds). |
| finished_at | integer | The time the task finished. Unix timestamp (seconds). |
Handling by status โ
| Status | Meaning | Handling |
|---|---|---|
queued | Waiting to generate | Keep querying the status |
in_progress | Generating | Keep querying the status |
completed | Generation complete | Download the image from data.url |
failed | Generation failed | Check the error response |
cancelled | Cancelled | Stop querying |
incomplete | Ended in an incomplete state | Check the reason it ended |
Response example โ
{
"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
}Reference input and result addresses โ
Pass a downloadable original image URL in input.content.image_url. Image reference input is separate from material library registration.
The generation result is received from data.url. For the returned COS download URL, use the full address including the query string, and save the file before it expires. The URL of an image generation result and the asset://<id> for video are different values.
Output size โ
size is the requested size. Even in text-based generation, Flash may return an image whose size and ratio differ from the request. Before saving, check the actual width, height, and aspect ratio of the result file.
Pixel specs by ratio โ
| Ratio | 1K resolution | 2K resolution | 4K resolution |
|---|---|---|---|
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 |
Error codes โ
See API error codes.