tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideImage Generation ModelsVidu Image Generation API Guide

Vidu Image Generation API Guide

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-10 22:08:17
Diterjemahkan oleh AI

Overview

Vidu is a multimodal generative model series launched by Shengshu Technology. This document describes how to call the Vidu image generation model Vidu-Image-q2 (vidu-image-q2) through TokenHub, which supports reference-to-image, text-to-image, and image editing: generate images by combining 0 to 7 reference images with text prompts, or perform text-to-image using text alone.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Note:
In all examples below, YOUR_API_KEY must be replaced with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Call Process

Image generation is a time-consuming task, so the API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call the image generation API, which returns a task_id and the initial status created upon success.
2. Poll for results: Call the query task result API with the task_id until state = success, and obtain the image URL from the result. You can also configure a callback through callback_url, so that the server actively pushes notifications when the task status changes.
Note:
Task status: created (successfully created) / queueing (in queue) / processing (in progress) / success (succeeded) / failed (failed).
All API responses include request_id (at the top level, used for troubleshooting). Query APIs additionally return usage (usage consumption).

Model List

Model Name
model Parameter Value
Supported Capability
Prompt Limit
Resolution
Aspect Ratio
Vidu-Image-q2
vidu-image-q2
Reference-based image generation / text-to-image / image editing
2000 characters
1080p / 2K / 4K
16:9,9:16,1:1,3:4,4:3,21:9,2:3,3:2,auto

Image Generation

1. API Description

The Vidu image generation (reference-to-image) API supports reference-to-image, text-to-image, and image editing: generate images with 0 to 7 reference images + text prompts, or perform text-to-image when no reference images are provided.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model ID. Value: vidu-image-q2
prompt
Yes
string
Text prompt, with a maximum length of 2000 characters. If images is not passed, image-to-text generation is performed based on this text.
images
No
array[string]
Reference images, 0 to 7. Supports image URL or Base64 (with the data:image/png;base64, prefix required). Format png/jpeg/jpg/webp; pixels greater than or equal to 128×128; aspect ratio must be less than 1:4 or greater than 4:1; single image no more than 50 MB; POST body no more than 20 MB.
aspect_ratio
No
string
Aspect ratio. Options: 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto (consistent with the aspect ratio of the first input image). Default value: 16:9.
resolution
No
string
Resolution. Options: 1080p / 2K / 4K. Default value: 1080p.
seed
No
integer
Random seed. If not specified or set to 0, a random number is used.
callback_url
No
string
Callback URL for task status changes (POST). The callback body is consistent with the response body of the query task, and authentication is performed using the callback signature algorithm.

3. Sample Request

Reference-to-image
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://example.com/reference.jpg"],
  "prompt": "a cat sitting on a windowsill at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'
Text-to-image (without 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"
}'

4. Output Parameters

Field
Type
Description
task_id
string
Task ID generated by Vidu, used for subsequent task queries and callback matching.
state
string
Processing status: created / queueing / processing / success / failed.
prompt
string
Prompt parameter of this call.
created_at
string
Task creation time (ISO 8601).
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

{
    "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"
}

6. Error Codes

When a request fails, an error code is returned. For details, see ErrMsg/Error Message. For common error codes, see Appendix: Unified Error Codes.

Querying the Task Result

1. API Description

Query the status and results of an image generation task. After a task is submitted and a task_id is returned, poll this API to obtain the results.
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 (represented by YOUR_TASK_ID in the example). Image generation takes approximately several seconds to tens of seconds, so polling every 3 to 5 seconds is recommended.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID (path parameter), which is the task_id returned when the task is submitted.

3. Sample Request

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

4. Output Parameters

Field
Type
Description
state
string
Processing status: created / queueing / processing / success / failed.
model
string
Model name used in this call.
aspect_ratio
string
Aspect ratio parameter of this call.
resolution
string
Resolution parameter of this call.
creations
array[object]
List of generated 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 promptly.
request_id
string
Unique request identifier used for troubleshooting.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Sample Response

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 }
}

6. Error Codes

state
Description
Handling Recommendation
success
Generation succeeded
Obtain the result image from creations[].url.
processing / queueing
Processing / queued
Poll once every 3 to 5 seconds until the status changes to success.
failed
Generation failed
Check the failure cause, make modifications, and retry. If the failure persists, 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 is missing or empty
Missing required field
FieldUnwanted
unwanted field
Unwanted field was passed.
FieldInvalid
invalid field
Input parameter failed validation.
FieldItemCountOutOfRange
field item count out of range
The number of field items exceeds the limit (for example, the number of images exceeds the limit).
PageSizeOutOfRange
page size out of range
Image size/parameter exceeds the limit.
ImageFormatInvalid
invalid image format
Image format does not meet the requirements.
ImageSizeInvalid
image size invalid
Image size is too large or too small.
ImageDownloadFailure
image download failure
Failed to download the image from the URL. Check the link.
TaskPromptPolicyViolation
prompt policy violation
Prompt triggers security review and risk control.
CreationPolicyViolation
creation policy violation
Generated content triggers risk control.
AuditSubmitIllegal
submit is illegal
Input failed security review.
CreditInsufficient
insufficient credits
Insufficient credits
ModelUnavailable
model unavailable
Model unavailable
Unauthorized
unauthorized
Unauthenticated (check Authorization)
Forbidden
forbidden
Request has no permission.
TaskNotFound
task not found
task_id not found.
QuotaExceeded
quota exceeded
Exceeding the concurrency limit
TooManyRequests
too many requests
Requests are too frequent.
InternalServiceFailure
internal service failure
Internal server error

General Constraints on Image Assets

Format: png / jpeg / jpg / webp. Resolution: at least 128×128 pixels. Aspect ratio: must be less than 1:4 or greater than 4:1. Single image size: no more than 50 MB. POST body size: no more than 20 MB. Image URL or Base64 is supported (Base64 must include the data:image/png;base64, prefix).

FAQs

1. How to Distinguish Text-to-Image from Image-to-Image?

The same API supports both modes: passing images enables reference-to-image (using the subjects in the images as references), while omitting images enables text-to-image (generated solely from the prompt). vidu-image-q2 supports both modes.

2. Do Generated Image Links Expire?

The generated result is a temporary address that expires in 12 hours. Download the image from creations[].url promptly after the task succeeds and save it to your own storage. Do not rely on this link for a long time.

3. What Is the auto Aspect Ratio?

aspect_ratio: auto indicates that the output aspect ratio remains consistent with the first input image. This setting is meaningful only in reference-to-image mode.

Topik sebelumnya: Hy Image Generation API GuideTopik selanjutnya: Seedream Image Generation API Guide

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation