Skip to content

Vega Image โ€‹

Updated

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 โ€‹

ItemValue
Call pathTokenhub API
Pro model IDwand-vega-image-pro
Flash model IDwand-vega-image-flash
Lite model IDwand-vega-image-lite
Guardrail bypass supportSupported

Supported specs by version โ€‹

VersionResolutionRatioReference images
wand-vega-image-pro1K / 2K / 4K1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9Up to 10
wand-vega-image-flash1K / 2K / 4K1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9Up to 10
wand-vega-image-lite1K / 2K / 4K1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 9:16 / 16:9 / 21:9Up 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 โ€‹

VersionNumber of reference imagesRecommended size per fileFormats
wand-vega-image-proUp to 1020MB or lessPNG / JPEG
wand-vega-image-flashUp to 1020MB or lessPNG / JPEG
wand-vega-image-liteUp to 1020MB or lessPNG / 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.

  1. Submit the task: Call the image generation API. On success, task_id is returned.
  2. Poll for the result: Until it becomes status = completed, call the task result query API 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 โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel ID. wand-vega-image-pro / wand-vega-image-flash / wand-vega-image-lite
promptRequiredstringThe text prompt; its length must be 2000 characters or fewer. If there is no reference image, the image is generated based on this text.
inputOptionalarray[object]The multimodal input content array used in image-transform / reference-image scenarios.
input.contentOptionalarray[object]An array of input content segments. They are concatenated in order to compose a multimodal prompt.
input.content.typeOptionalstringContent type. Value: input_image (reference image).
input.content.image_urlOptionalstringReference image URL. For the per-version count, per-file size, and formats, check the reference image specs.
sizeOptionalstringThe output image size in ${width}x${height} format.

Request examples โ€‹

Text-based image generation

bash
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

bash
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 โ€‹

ParameterTypeDescription
task_idstringThe task ID. Used for result queries and callback correlation.
request_idstringA unique request identifier used for troubleshooting.

Response example โ€‹

json
{
  "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 โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task_id task ID returned when the task was submitted (a path parameter).

Request example โ€‹

bash
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 โ€‹

FieldTypeDescription
statusStringTask status. See the handling by status below
request_idstringA unique request identifier used for troubleshooting.
dataarray[object]The list of generated results.
data[].urlstringThe download URL of the generated image. It is a temporary URL that includes a signature, so download and save it within its validity period.
usageobjectUsage.
usage.total_tokensintegerThe number of tokens consumed by this task, used for billing and settlement.
created_atintegerThe time the task was created. Unix timestamp (seconds).
finished_atintegerThe time the task finished. Unix timestamp (seconds).

Handling by status โ€‹

StatusMeaningHandling
queuedWaiting to generateKeep querying the status
in_progressGeneratingKeep querying the status
completedGeneration completeDownload the image from data.url
failedGeneration failedCheck the error response
cancelledCancelledStop querying
incompleteEnded in an incomplete stateCheck the reason it ended

Response example โ€‹

json
{
  "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 โ€‹

Ratio1K resolution2K resolution4K resolution
1:11024ร—1024 / 1080ร—10802048ร—2048 / 2160ร—21604096ร—4096
2:31024ร—1536 / 1080ร—16201440ร—21603328ร—4992
3:21536ร—1024 / 1620ร—10802160ร—14404992ร—3328
3:41080ร—14401440ร—1920 / 2160ร—28803584ร—4800
4:31440ร—10801920ร—1440 / 2880ร—21604800ร—3584
9:16720ร—1280 / 1080ร—19201440ร—25602160ร—3840
16:91280ร—720 / 1920ร—10802560ร—14403840ร—2160
21:91512ร—6482520ร—10805040ร—2160

Error codes โ€‹

See API error codes.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages