Skip to main content
POST
/
vidu
/
ent
/
v2
/
reference2image
curl --request POST \
  --url https://api.powertokens.ai/vidu/ent/v2/reference2image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "viduq2",
  "prompt": "A cute kitten playing on grass under sunny weather",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "seed": 42
}
'
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq2",
  "images": [
    "your_image_url1",
    "your_image_url2",
    "your_image_url3"
  ],
  "prompt": "your_prompt",
  "seed": 0,
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "payload": "",
  "credits": 2,
  "created_at": "2025-09-08T09:53:22.083033428Z"
}

Authorizations

​
Authorization
string
header
required

Pass Authorization: Bearer <token> in the request header.

Body

application/json
​
model
enum<string>
required

Image generation model name.

  • viduq2: Supports text-to-image, image editing, and reference-to-image with better results
Available options:
viduq2
​
prompt
string
required

Text prompt for describing image generation content, with a maximum length of 2000 characters. Note: viduq2 supports generating images using only prompt (without reference images).

Maximum string length: 2000
​
images
string[]

Reference image list.

  • viduq2: Supports input of 0 to 7 images The model will generate an image with consistent subjects based on the input images.
  • Supports Base64 or URL format (URL must be accessible)
  • Supported formats: png, jpeg, jpg, webp
  • Image resolution must be no smaller than 128×128
  • Aspect ratio must be between 1:4 and 4:1
  • Single image size must not exceed 50MB
  • The post body of the HTTP request should not exceed 20MB, and encoding must include proper content type string
  • Base64 format example: data:image/png;base64,{base64_encode}
Maximum array length: 7
​
seed
integer

Random seed.

  • Defaults to a random seed number
  • Manually set values will override the default random seed
​
aspect_ratio
enum<string>
default:16:9

Image aspect ratio.

  • viduq2: Default 16:9, optional values: 16:9, 9:16, 1:1, 3:4, 4:3, 21:9, 2:3, 3:2
  • auto: Generated image aspect ratio is consistent with the first input image
Available options:
16:9,
9:16,
1:1,
3:4,
4:3,
21:9,
2:3,
3:2,
auto
​
resolution
enum<string>
default:1080p

Image resolution.

  • viduq2: Default 1080p, optional values: 1080p, 2K, 4K
Available options:
1080p,
2K,
4K
​
payload
string

Transparent transmission parameters. No processing, only data transmission, with a maximum length of 1048576 characters.

Maximum string length: 1048576
​
callback_url
string

Callback When creating a task, you need to actively set the callback_url with a POST request. When the video generation task changes its status, Vidu will send a callback request to this URL, containing the latest status of the task. The structure of the callback request content will be the same as the return body of the Get Generation API. The "status" in the callback response includes the following states:

  • processing: Task is being processed.
  • success: Task is completed (if sending fails, it will retry the callback three times).
  • failed: Task failed (if sending fails, it will retry the callback three times). Vidu uses a callback signature algorithm for verification, check out the details here: Callback Signature

Response

Submission successful, returns an image task object.

​
task_id
string

Task ID.

​
state
enum<string>

Task processing state:

  • created: Task created successfully
  • queueing: Task in queue
  • processing: Task processing
  • success: Generation successful
  • failed: Task failed
Available options:
created,
queueing,
processing,
success,
failed
​
model
string

Model parameter used for this call.

​
prompt
string

Text prompt used for this call.

​
images
string[]

Images used for this call.

​
seed
integer

Random seed parameter used for this call.

​
aspect_ratio
string

Aspect ratio parameter used for this call.

​
resolution
string

Resolution parameter used for this call.

​
credits
integer

Credits consumed for this call.

​
callback_url
string

Callback URL parameter used for this call.

​
payload
string

Payload parameter used for this call.

​
created_at
string<date-time>

Task creation time.