Vidu โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generationAuthentication: Tokenhub API Key / Bearer
Vidu Image q2 is an image generation model that supports text-to-image, reference-image generation (0โ7 images), and image editing.
Basic Information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Supported |
Supported Specifications by Version โ
| Version | Resolution | Ratio | Reference image |
|---|---|---|---|
vidu-image-q2 | 1080p / 2K / 4K | 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto | Up to 7 images |
Call Procedure โ
Image generation is a time-consuming operation, so API uses an asynchronous call pattern consisting of the following two steps.
- Submit the task: Call the image generation API. On success,
task_idand the initial statecreatedare returned. - Poll for the result: Call the task result query API with
task_iduntil the state becomesstate = success, then retrieve the image URL from the result. By configuring a callback withcallback_url, you can have the server send a notification whenever the task state changes.
Note: Task states: created (creation complete) / queueing (in queue) / processing (in progress) / success (succeeded) / failed (failed). Every API response includes a top-level request_id used for troubleshooting. The query API also returns usage, which indicates usage.
Image Generation โ
API Description โ
Vidu image generation (reference-image based generation) API supports reference-image based generation, text-to-image generation, and image editing. You can generate an image from a reference image 0~7 plus a text prompt, or perform text-to-image generation without providing a reference image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model ID. Value: vidu-image-q2 |
| prompt | Required | string | Text prompt, with a maximum length of 2000 characters. If images is not passed, text-to-image generation is performed based on this text. |
| images | Optional | array[string] | 0~7 reference images. Image URLs or Base64 are supported; Base64 requires the data:image/png;base64, prefix. Formats: png/jpeg/jpg/webp. Pixel dimensions: 128ร128 or greater. Aspect ratio: must be less than 1:4 or greater than 4:1. Up to 50 MB per image 1, and up to 20 MB for the POST body. |
| aspect_ratio | Optional | string | Aspect ratio. Options: 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto (same as the aspect ratio of the first input image). Default: 16:9. |
| resolution | Optional | string | Resolution. Options: 1080p / 2K / 4K. Default: 1080p. |
| seed | Optional | integer | Random seed. If not specified or set to 0, a random number is used. |
| callback_url | Optional | string | Callback URL for task state changes (POST). The callback body is identical to the task query response body, and is authenticated with the callback signature algorithm. |
Request Examples โ
Reference-image based generation
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"
}'Text-to-image generation (no images)
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"
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| task_id | string | The task ID generated by Vidu, used for subsequent task queries and callback matching. |
| state | string | Processing state: created / queueing / processing / success / failed. |
| prompt | string | The prompt parameter of this call. |
| created_at | string | Task creation time (ISO 8601). |
| request_id | string | A unique request identifier used for troubleshooting. |
Response Example โ
{
"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"
}Error Codes โ
If a request fails, an error code is returned. For details, see ErrMsg/error message. For common error codes, see Appendix: Unified Error Codes.
Querying Task Results โ
API Description โ
Queries the state and result of an image generation task. After submitting a task and receiving task_id, poll this API to retrieve the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/{task_id}
Note: The {task_id} in the path is the task_id returned when the task was submitted, shown as YOUR_TASK_ID in the examples. Image generation takes roughly a few seconds to a few dozen seconds, so polling every 3~5 seconds is recommended.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task_id task ID returned when the task was submitted (path parameter). |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| state | string | Processing state: created / queueing / processing / success / failed. |
| model | string | The model name used in this call. |
| aspect_ratio | string | The aspect ratio parameter of this call. |
| resolution | string | The resolution parameter of this call. |
| creations | array[object] | The list of generation results, returned on success. |
| creations[].url | string | The download URL of the generated image is a temporary address valid for 12 hours. Download and save it immediately. |
| request_id | string | A unique request identifier used for troubleshooting. |
| tokenhub_usage | object | Usage. |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing/settlement. |
Response Examples โ
Generation succeeded:
{
"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
}
}Error Codes โ
| state | Description | Recommended handling |
|---|---|---|
| success | Generation succeeded | Retrieve the resulting image from creations.url. |
| processing / queueing | In progress / in queue | Poll once every 3~5 seconds until the state changes to success. |
| failed | Generation failed | Identify and fix the cause of failure, then retry. If failures persist, contact technical support and provide the request_id. |
For request-level error codes, see Appendix: Unified Error Codes.
Appendix โ
Unified Error Codes โ
| Error code | Error message | Description |
|---|---|---|
| BadRequest | Bad request | Invalid request |
| FieldLacking | Field missing or empty | A required field is missing |
| FieldUnwanted | Unwanted field | A field that is not allowed was passed. |
| FieldInvalid | Invalid field | An input parameter failed validation. |
| FieldItemCountOutOfRange | Field item count out of range | The number of field items exceeded the limit (for example, the number of images exceeded the limit). |
| PageSizeOutOfRange | Page size out of range | The image size/parameter exceeded the limit. |
| ImageFormatInvalid | Invalid image format | The image format does not meet the requirements. |
| ImageSizeInvalid | Invalid image size | The image size is too large or too small. |
| ImageDownloadFailure | Image download failed | The image could not be downloaded from the URL. Check the link. |
| TaskPromptPolicyViolation | Prompt policy violation | The prompt triggered security review and risk control. |
| CreationPolicyViolation | Creation policy violation | The generated content triggered risk control. |
| AuditSubmitIllegal | Submission is invalid | The input did not pass security review. |
| CreditInsufficient | Insufficient credit | Credit is insufficient. |
| ModelUnavailable | Model unavailable | The model is unavailable. |
| Unauthorized | Unauthorized | Not authenticated (check Authorization). |
| Forbidden | Forbidden | The request lacks permission. |
| TaskNotFound | Task not found | The task_id could not be found. |
| QuotaExceeded | Quota exceeded | The concurrency limit was exceeded. |
| TooManyRequests | Too many requests | The request frequency is too high. |
| InternalServiceFailure | Internal service error | Internal server error |
General Limits for Image Assets โ
Formats: png / jpeg / jpg / webp. Resolution: minimum 128ร128 pixels. Aspect ratio: must be less than 1:4 or greater than 4:1. Image 1 size: up to 50 MB. POST body size: up to 20 MB. Image URLs or Base64 are supported; Base64 must include the data:image/png;base64, prefix.
FAQ โ
1. How do I distinguish text-to-image generation from image-to-image generation? โ
The same API supports both modes. Passing images enables reference-image based generation that references the target within the image, while omitting images enables text-to-image generation driven by the prompt alone. vidu-image-q2 supports both modes.
2. Do generated image links expire? โ
Generation results are temporary addresses that expire after 12 hours. Immediately after the task succeeds, download the image from creations.url and save it to your own storage. Do not rely on this link long term.
3. What is the auto aspect ratio? โ
aspect_ratio: auto indicates that the output aspect ratio stays identical to that of the first input image. This setting is only meaningful in reference-image based generation mode.