> ## Documentation Index > Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Vidu Q4 Reference to Video > The Vidu Q4 Reference to Video API builds a 3–16 second video from 1–12 reference images and up to 3 voice clips, with optional audio and up to 4K. > [!TIP] > > 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`. > 2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](https://docs.vidgo.ai/api-manual/task-management/status.md) endpoint. Vidu Q4 Reference to Video builds a 3–16 second video from up to 12 reference images (characters, products, outfits, locations) and up to 3 voice clips, with optional native audio and output up to 4K. Use it for recurring characters in short series, ads that combine a product, a model and a location, and dubbed character clips. Vidu Q4 is ShengShu Technology's video model, released upstream as Vidu Q4 Preview in October 2026. It has no text-to-video mode: every request starts from images. Vidgo exposes two model IDs: [Image to Video](https://docs.vidgo.ai/api-manual/video-series/vidu-q4-image-to-video.md) and [Reference to Video](https://docs.vidgo.ai/api-manual/video-series/vidu-q4-reference-to-video.md). ## Models * **vidu/q4/reference-to-video** — Reference-to-video with Vidu Q4 from 1–12 images and up to 3 voice references, 3–16 seconds, 540p to 4K. ## Features * Reference-to-video with 1–12 reference images in one request. * Up to 3 voice references through `reference_audio_urls`. * Prompt tags `[@reference_image_N]` and `[@reference_audio_N]` to say which reference goes where. * Optional native audio with `generate_audio`. * Five aspect ratios and five resolutions from `540p` to `4k`. * Integer durations from 3 to 16 seconds. ## Required parameters * `prompt` (string): The scene and how each reference is used. Must not be blank; up to 5,000 characters. * `reference_image_urls` (string\[]): 1–12 public HTTP(S) image URLs. ## Optional parameters * `reference_audio_urls` (string\[]): Up to 3 public HTTP(S) audio URLs used as voice references. Short, clean MP3 voice clips work best. * `aspect_ratio` (string): `16:9`, `9:16`, `4:3`, `3:4` or `1:1`. When omitted, the upstream default (16:9) applies. * `generate_audio` (boolean): Generate native audio with the video. When omitted, no audio is generated. * `duration` (integer): Output length in seconds, `3`–`16`. Default `5`. * `resolution` (string): `540p`, `720p`, `1080p`, `2k` or `4k` (case-insensitive). Default `720p`. * `enable_safety_checker` (boolean): Turn the upstream safety checker on or off. ## Resolution | `resolution` | Use it for | | - | - | | `540p` | Fast, low-cost drafts | | `720p` | Default; social and web clips | | `1080p` | Full HD delivery | | `2k` | High-resolution masters | | `4k` | Hero shots and large screens | The resolution sets the per-second billing rate. ## Output The finished task returns one MP4 video in the `files` array of [Query Task Status](https://docs.vidgo.ai/api-manual/task-management/status.md) and the callback payload. ## Examples * **Two reference images, 720p**: a model and a sneaker referenced as `[@reference_image_1]` and `[@reference_image_2]`, vertical `9:16`. * **Character with voice reference and audio, 1080p**: a character and a location, one voice clip referenced as `[@reference_audio_1]`, quoted dialogue, `generate_audio: true` and a `callback_url`. ## Notes * References are numbered by array order: the first URL in `reference_image_urls` is `[@reference_image_1]`, the first URL in `reference_audio_urls` is `[@reference_audio_1]`. * `image_urls` is not accepted on this ID and returns 400. To animate a single start frame, use [Vidu Q4 Image to Video](https://docs.vidgo.ai/api-manual/video-series/vidu-q4-image-to-video.md). Vidu Q4 has no text-to-video mode. * More than 12 reference images or more than 3 audio references return 400. * `model` and `callback_url` belong at the request root, not inside `input`. * Credits are reserved at submission and depend on `resolution` and `duration` (per output second). Reference images, reference audio and `generate_audio` do not change the rate. A failed task is refunded in full. See the [pricing page](https://vidgo.ai/apis/api-pricing) for current rates. ## OpenAPI ````yaml api-manual/video-series/vidu-q4-reference-to-video.json POST /api/generate/submit openapi: 3.0.0 info: title: Vidgo API - Vidu Q4 Reference to Video description: >- The Vidu Q4 Reference to Video API builds a 3–16 second video from 1–12 reference images and up to 3 voice clips, with optional audio and up to 4K. version: 1.0.0 servers: - url: https://api.vidgo.ai description: Production server security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Video Series summary: Vidu Q4 Reference to Video description: >- Send only the `input` fields listed for this model. Any other field, including `image_urls`, returns 400. Reference URLs must be public HTTP(S) URLs without embedded credentials. operationId: submit_vidu_q4_reference_to_video requestBody: required: true content: application/json: schema: type: object required: - model - input properties: model: type: string description: Model ID. Use `vidu/q4/reference-to-video`. example: vidu/q4/reference-to-video callback_url: type: string format: uri nullable: true description: >- Optional public HTTP(S) endpoint that receives a POST when the task becomes `finished` or `failed`. HTTPS is recommended. Omit it, or send `null` or an empty string, to disable callbacks. example: https://your-domain.com/callback input: type: object required: - prompt - reference_image_urls properties: prompt: type: string minLength: 1 maxLength: 5000 example: >- [@reference_image_1] walks into the cafe from [@reference_image_2] and greets the barista, speaking in the voice of [@reference_audio_1] description: >- Describe the scene and how the references are used. Refer to them by array order as `[@reference_image_1]`, `[@reference_audio_1]` and so on. Must not be blank; up to 5,000 characters. reference_image_urls: type: array items: type: string format: uri minItems: 1 maxItems: 12 example: - https://example.com/character.png - https://example.com/cafe.png description: >- 1–12 public HTTP(S) reference image URLs: characters, products, outfits or locations. reference_audio_urls: type: array items: type: string format: uri maxItems: 3 example: - https://example.com/voice.mp3 description: >- Up to 3 public HTTP(S) audio URLs used as voice references. Short, clean MP3 voice clips work best. duration: type: integer minimum: 3 maximum: 16 default: 5 description: >- Output length in seconds (integer, an integer string such as `"5"` is also accepted). resolution: type: string enum: - 540p - 720p - 1080p - 2k - 4k default: 720p description: >- Output resolution (case-insensitive). It sets the billing rate. aspect_ratio: type: string enum: - '16:9' - '9:16' - '4:3' - '3:4' - '1:1' description: >- Output aspect ratio. When omitted, the upstream default (16:9) applies. generate_audio: type: boolean description: >- Generate native audio with the video. When omitted, the upstream default (no audio) applies. Does not change the price. enable_safety_checker: type: boolean description: >- Turn the upstream safety checker on or off. When omitted, the upstream default applies. additionalProperties: false description: Generation parameters. examples: images_only: summary: Two reference images, 720p value: model: vidu/q4/reference-to-video input: prompt: >- [@reference_image_1] holds up the sneaker from [@reference_image_2] and spins it slowly under studio light reference_image_urls: - https://example.com/model.png - https://example.com/sneaker.png duration: 5 resolution: 720p aspect_ratio: '9:16' voice_reference: summary: Character with voice reference and audio, 1080p value: model: vidu/q4/reference-to-video callback_url: https://your-domain.com/callback input: prompt: >- [@reference_image_1] walks into the cafe from [@reference_image_2] and greets the barista, speaking in the voice of [@reference_audio_1]: "Morning! The usual, please." reference_image_urls: - https://example.com/character.png - https://example.com/cafe.png reference_audio_urls: - https://example.com/voice.mp3 duration: 8 resolution: 1080p aspect_ratio: '16:9' generate_audio: true responses: '200': description: Task submitted content: application/json: schema: type: object required: - code - data properties: code: type: integer enum: - 200 description: HTTP status code. data: type: object required: - task_id - status - created_time properties: task_id: type: string description: >- Task ID. Use it with [Query Task Status](/api-manual/task-management/status). status: type: string enum: - not_started description: Initial task status. created_time: type: string format: date-time description: Time the task was created (ISO 8601). example: code: 200 data: task_id: task-unified-1762160000-abc123 status: not_started created_time: '2026-11-03T10:30:00' '400': description: >- Invalid input, unsupported field, inaccessible media, or insufficient credits content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '401': description: Invalid credentials content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '403': description: Access denied content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '404': description: Unknown or disabled model content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '408': description: Request timed out content: text/plain: schema: type: string example: Request timeout '422': description: Invalid JSON or non-object request body content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '429': description: Rate or API key credit limit exceeded content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '500': description: Internal error content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '502': description: Unable to create the upstream generation task content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. '503': description: The requested model is temporarily unavailable content: application/json: schema: type: object required: - detail properties: detail: oneOf: - type: string - type: object additionalProperties: true - type: array items: {} description: Error message. components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- All API endpoints require Bearer Token authentication Get your API Key: Go to **Dashboard → API Key** ([API Key Management Page](https://vidgo.ai/apis/dashboard/api-key)) to get your API Key Add it to the request header: ``` Authorization: Bearer VIDGO_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.