> ## Documentation Index > Fetch the complete documentation index at: https://docs.powertokens.ai/llms.txt > Use this file to discover all available pages before exploring further. # Vidu Reference-to-Video viduq3-turbo > Generate videos using the Vidu model based on reference subjects. Supports defining characters/objects through images and text, and referencing them in prompts. After submission, query status via `GET /vidu/ent/v2/tasks/{task_id}`. Uses model viduq3-turbo. ## OpenAPI ````yaml api-reference/en/zmodelVideo/vidu/viduq3-turbo-reference-to-video.json POST /vidu/ent/v2/reference2video openapi: 3.0.1 info: title: Vidu Reference-to-Video (viduq3-turbo) version: 1.0.0 servers: - url: https://api.powertokens.ai security: [] paths: /vidu/ent/v2/reference2video: post: summary: Vidu Reference-to-Video (viduq3-turbo) description: >- Generate videos using the Vidu model based on reference subjects. Supports defining characters/objects through images and text, and referencing them in prompts. After submission, query status via `GET /vidu/ent/v2/tasks/{task_id}`. Uses model viduq3-turbo. operationId: viduReferenceToVideoEnViduq3Turbo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferenceToVideoRequest' examples: basic_reference_video: summary: Basic reference-to-video value: model: viduq3-turbo subjects: - name: XiaoMing images: - https://example.com/xiaoming.png - name: XiaoHong images: - https://example.com/xiaohong.png prompt: >- @XiaoMing and @XiaoHong are cooking together, and both say they love hot pot. duration: 5 with_audio_generation: summary: Reference video with audio generation (q3 model) value: model: viduq3-turbo auto_subjects: false subjects: - name: CharacterA images: - data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAE... voice_id: voice_123456 audio: true audio_type: all prompt: '@CharacterA is introducing product features' duration: 8 resolution: 1080p multi_image_subject: summary: Multi-image subject reference value: model: viduq3-turbo subjects: - name: Product images: - https://example.com/product_front.jpg - https://example.com/product_side.jpg - https://example.com/product_back.jpg prompt: '@Product rotates on the display stand' aspect_ratio: '1:1' seed: 42 responses: '200': description: Submission successful, returns a video task object. content: application/json: schema: $ref: '#/components/schemas/ReferenceToVideoResponse' examples: success: summary: Submission successful value: task_id: your_task_id_here state: created model: viduq3-turbo prompt: >- @1 and @2 are cooking together, and both say they love hot pot. duration: 8 seed: 123456789 resolution: 1080p payload: '' off_peak: false credits: '15' created_at: '2025-01-01T15:41:31.968916Z' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_request: summary: Invalid parameters value: code: bad_request_body message: Request body format error or invalid field values data: null '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized value: code: access_denied message: Invalid token data: null '429': description: Rate limit exceeded or insufficient quota. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quota_exceeded: summary: Insufficient quota value: code: insufficient_user_quota message: Insufficient account quota, please try again later data: null '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: server_error: summary: Server error value: code: internal_server_error message: Internal server error, please try again later data: null security: - BearerAuth: [] components: schemas: ReferenceToVideoRequest: type: object required: - model - subjects - prompt properties: model: type: string enum: - viduq3-turbo description: >- Video generation model name. - **viduq3-turbo**: Supports intelligent scene switching and simultaneous audio and video output, boasts the fastest generation speed, and offers the highest cost-effectiveness auto_subjects: type: boolean default: false description: >- Whether to use the intelligent entity library capability. - **true**: Utilize the capabilities of the intelligent agent library - **false**: Do not use the intelligent agent library capability subjects: type: array minItems: 1 maxItems: 7 items: $ref: '#/components/schemas/Subject' description: >- List of subjects. - When using q3, q2, q1, and 2.0 series models, only image and text subjects can be used, with a maximum of 7 subjects - When using the q2-pro model, video subjects, text subjects, and image subjects can be employed, with no more than 4 image or text subjects, and no more than 2 video subjects (or 1 temporary video subject) - viduq3-mix does not support the use of entities for the time being prompt: type: string maxLength: 5000 description: >- Text prompt for describing video generation content, with a maximum length of 5000 characters. You can reference subject content using @subject_name. For example: `@XiaoMing and @XiaoHong are cooking together, and both say they love hot pot.` audio: type: boolean default: false description: >- Whether to enable audio-video output capability. - **false**: Outputs silent video - **true**: Outputs video with generated speech and background music based on the prompt Note: audio defaults to true for viduq3 and viduq3-turbo, and false for other models audio_type: type: string enum: - all - speech_only - sound_effect_only default: all description: |- Audio type, required when audio is true. - **all**: Sound effects + vocals - **speech_only**: Vocal only - **sound-effect_only**: Sound effects only duration: type: integer description: |- Video duration in seconds. Default values vary by model: - **viduq3, viduq3-turbo**: default 5, available: 3-16 - **viduq2**: default 5, available: 1-10 - **viduq1**: default 5, available: 5 - **vidu2.0**: default 4, available: 4 minimum: 3 maximum: 16 default: 5 seed: type: integer description: |- Random seed. - Defaults to a random seed number - Manually set values will override the default random seed aspect_ratio: type: string enum: - '16:9' - '9:16' - '1:1' default: '16:9' description: |- The aspect ratio of the output video. - Default: 16:9 - Accepted values: 16:9, 9:16, 1:1 Note: q2, q3 models support any aspect ratio resolution: type: string enum: - 360p - 540p - 720p - 1080p description: >- Resolution (based on model & duration): - **viduq3, viduq3-turbo (3-16s)**: default 720p, options: 540p, 720p, 1080p - **viduq2 (1-10s)**: default 720p, options: 540p, 720p, 1080p - **viduq1 (5s)**: default 1080p, options: 1080p - **vidu2.0 (4s)**: default 360p, options: 360p, 720p payload: type: string maxLength: 1048576 description: >- Transparent transmission parameters. No processing, only data transmission, with a maximum length of 1048576 characters. off_peak: type: boolean default: false description: >- Off peak mode. - **true**: Off peak generate mode - **false**: Normal generate mode Notes: 1. The off_peak mode consumes lower points (see Pricing for details) 2. Tasks submitted in off peak mode will be generated within 48 hours. Tasks that are not completed will be automatically cancelled and their points will be refunded 3. We also support cancel off_peak tasks 4. The q3 model supports peak-shifting tasks when the audio parameter is true; the q2, q1, and 2.0 series models support peak-shifting tasks when the audio parameter is false callback_url: type: string description: >- 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 server_id: type: string description: >- Subject ID obtained from the Create Subject API. Required when using an existing subject. - See [Create and Use Subject Library] for creating subjects. watermark: type: boolean description: >- Whether to add a watermark. - **true**: Add watermark - **false**: Do not add watermark Note 1: Currently the watermark content is fixed, default is no watermark Note 2: You can retrieve watermarked video content through the watermarked_url parameter in the query task API default: false wm_position: type: integer description: |- Watermark position on the image. Options: - **1**: Top left - **2**: Top right - **3**: Bottom right - **4**: Bottom left Default: 3 default: 3 enum: - 1 - 2 - 3 - 4 minimum: 1 maximum: 4 x-options: - label: Top Left value: 1 - label: Top Right value: 2 - label: Bottom Right value: 3 - label: Bottom Left value: 4 wm_url: type: string description: >- Watermark image URL. When not specified, the default watermark is used. meta_data: type: string description: >- Metadata identifier, a JSON format string used as a passthrough field. You can customize the format or use the example format below: ```json { "Label": "your_label", "ContentProducer": "your_content_producer", "ContentPropagator": "your_content_propagator", "ProduceID": "your_product_id", "PropagateID": "your_propagate_id", "ReservedCode1": "your_reserved_code1", "ReservedCode2": "your_reserved_code2" } ``` When this parameter is empty, the Vidu-generated metadata identifier is used by default. ReferenceToVideoResponse: type: object properties: task_id: type: string description: Task ID. state: type: string enum: - created - queueing - processing - success - failed description: |- Task processing state: - **created**: Task created successfully - **queueing**: Task in queue - **processing**: Task processing - **success**: Generation successful - **failed**: Task failed model: type: string description: Model parameter used for this call. prompt: type: string description: Text prompt used for this call. images: type: array items: type: string description: Images used for this call. duration: type: integer description: Video duration parameter used for this call. seed: type: integer description: Random seed parameter used for this call. aspect_ratio: type: string description: Aspect ratio parameter used for this call. resolution: type: string description: Resolution parameter used for this call. bgm: type: boolean description: Whether to use background music for this call. audio: type: boolean description: Whether to use audio for this call. audio_type: type: string description: Audio type parameter used for this call. payload: type: string description: Payload parameter used for this call. off_peak: type: boolean description: Off-peak mode parameter used for this call. credits: type: integer description: Credits consumed for this call. created_at: type: string format: date-time description: Task creation time. watermark: type: boolean description: 本次提交任务是否使用水印 ErrorResponse: type: object properties: code: type: string description: Error code. message: type: string description: Error description message. data: type: object nullable: true description: Additional error data (optional). Subject: type: object required: - name - images properties: name: type: string description: |- Subject name. Can be referenced in prompts via @subject_name. images: type: array minItems: 1 maxItems: 3 items: type: string description: >- URLs of images corresponding to the subject. - Each subject supports up to 3 images - Assets can be provided via URLs or Base64 encode - You must use one of the following codecs: PNG, JPEG, JPG, WebP - The dimensions of the images must be at least 128x128 pixels - The aspect ratio of the images must be between 1:4 and 4:1 - All images are limited to 50MB - The post body of the HTTP request should not exceed 20MB, and it must include an appropriate content type string - Base64 format example: `data:image/png;base64,{base64_encode}` videos: type: array items: type: string description: >- Subject video, the video URL corresponding to this subject. One of images or videos is required. Note 1: Only viduq2-pro model supports video subjects Note 2: Images and videos within each subject share 3 slots Note 3: Supports 1 video of 5 seconds Note 4: Supports video Base64 encoding or URL (must be accessible) Note 5: Video supports mp4, avi, mov formats Note 6: Video pixels must not be less than 128*128, and the aspect ratio must be less than 1:4 or greater than 4:1 Note 7: Base64 decoded byte length must be less than 20M, and encoding must include the appropriate content type string, e.g.: data:video/mp4;base64,{base64_encode} minItems: 1 maxItems: 1 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Pass `Authorization: Bearer ` in the request header.' ````