Skip to content

Vidu โ€‹

Updated

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

ItemValue
Call pathTokenhub API
Guardrail bypass supportSupported

Supported Specifications by Version โ€‹

VersionResolutionRatioReference image
vidu-image-q21080p / 2K / 4K16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / autoUp 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.

  1. Submit the task: Call the image generation API. On success, task_id and the initial state created are returned.
  2. Poll for the result: Call the task result query API with task_id until the state becomes state = success, then retrieve the image URL from the result. By configuring a callback with callback_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 โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel ID. Value: vidu-image-q2
promptRequiredstringText prompt, with a maximum length of 2000 characters. If images is not passed, text-to-image generation is performed based on this text.
imagesOptionalarray[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_ratioOptionalstringAspect 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.
resolutionOptionalstringResolution. Options: 1080p / 2K / 4K. Default: 1080p.
seedOptionalintegerRandom seed. If not specified or set to 0, a random number is used.
callback_urlOptionalstringCallback 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

bash
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)

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

FieldTypeDescription
task_idstringThe task ID generated by Vidu, used for subsequent task queries and callback matching.
statestringProcessing state: created / queueing / processing / success / failed.
promptstringThe prompt parameter of this call.
created_atstringTask creation time (ISO 8601).
request_idstringA unique request identifier used for troubleshooting.

Response Example โ€‹

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

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

Request Example โ€‹

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Parameters โ€‹

FieldTypeDescription
statestringProcessing state: created / queueing / processing / success / failed.
modelstringThe model name used in this call.
aspect_ratiostringThe aspect ratio parameter of this call.
resolutionstringThe resolution parameter of this call.
creationsarray[object]The list of generation results, returned on success.
creations[].urlstringThe download URL of the generated image is a temporary address valid for 12 hours. Download and save it immediately.
request_idstringA unique request identifier used for troubleshooting.
tokenhub_usageobjectUsage.
tokenhub_usage.total_tokensintegerThe number of tokens consumed by this task, used for billing/settlement.

Response Examples โ€‹

Generation succeeded:

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

stateDescriptionRecommended handling
successGeneration succeededRetrieve the resulting image from creations.url.
processing / queueingIn progress / in queuePoll once every 3~5 seconds until the state changes to success.
failedGeneration failedIdentify 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 codeError messageDescription
BadRequestBad requestInvalid request
FieldLackingField missing or emptyA required field is missing
FieldUnwantedUnwanted fieldA field that is not allowed was passed.
FieldInvalidInvalid fieldAn input parameter failed validation.
FieldItemCountOutOfRangeField item count out of rangeThe number of field items exceeded the limit (for example, the number of images exceeded the limit).
PageSizeOutOfRangePage size out of rangeThe image size/parameter exceeded the limit.
ImageFormatInvalidInvalid image formatThe image format does not meet the requirements.
ImageSizeInvalidInvalid image sizeThe image size is too large or too small.
ImageDownloadFailureImage download failedThe image could not be downloaded from the URL. Check the link.
TaskPromptPolicyViolationPrompt policy violationThe prompt triggered security review and risk control.
CreationPolicyViolationCreation policy violationThe generated content triggered risk control.
AuditSubmitIllegalSubmission is invalidThe input did not pass security review.
CreditInsufficientInsufficient creditCredit is insufficient.
ModelUnavailableModel unavailableThe model is unavailable.
UnauthorizedUnauthorizedNot authenticated (check Authorization).
ForbiddenForbiddenThe request lacks permission.
TaskNotFoundTask not foundThe task_id could not be found.
QuotaExceededQuota exceededThe concurrency limit was exceeded.
TooManyRequestsToo many requestsThe request frequency is too high.
InternalServiceFailureInternal service errorInternal 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.

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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages