> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vidu Reference-to-Video

> Use `POST /vidu/ent/v2/reference2video` to submit a subject-reference video generation task.

# Vidu Reference-to-Video

Vidu official format reference-to-video API, submitted as `application/json`.

* The routing endpoint is `POST /vidu/ent/v2/reference2video`.
* Currently submitted as `application/json`.
* Supports subject-reference video generation (multiple subjects).
* After a successful submission, the task `task_id` and `status` are returned. Use [Query Task](./query) to poll for results.

## Supported Models

* `viduq3-pro`: Efficiently generates high-quality audio and video content, making videos more vivid, realistic, and three-dimensional
* `viduq2-pro` / `viduq2-turbo`: New models with good results and rich details
* `viduq2-pro-fast`: Lowest price, fast generation speed
* `viduq1` / `viduq1-classic`: Clear visuals and stable camera movement
* `vidu2.0`: Fast generation speed

## Method and Path

```http theme={null}
POST /vidu/ent/v2/reference2video
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/vidu/ent/v2/reference2video \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "viduq3-pro",
      "subjects": [
        {
          "id": "subject_1",
          "images": ["https://example.com/subject.png"],
          "voice_id": "voice_001"
        }
      ],
      "prompt": "让@subject_1 向前走并微笑",
      "audio": true,
      "is_rec": false,
      "bgm": false,
      "duration": 5,
      "seed": 0,
      "resolution": "720p"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/vidu/ent/v2/reference2video",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "viduq3-pro",
          "subjects": [
              {
                  "id": "subject_1",
                  "images": ["https://example.com/subject.png"],
                  "voice_id": "voice_001"
              }
          ],
          "prompt": "让@subject_1 向前走并微笑",
          "audio": True,
          "is_rec": False,
          "bgm": False,
          "duration": 5,
          "seed": 0,
          "resolution": "720p"
      },
      timeout=60,
  )
  print(resp.json())
  ```
</CodeGroup>

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "task_id": "48038932-0ff5-4251-8b4b-7a76c09fd114",
    "status": "processing",
    "created_at": 1774494511
  }
  ```
</ResponseExample>

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  Model name. Supported: `viduq3-pro`, `viduq2-pro`, `viduq2-turbo`, `viduq2-pro-fast`, `viduq1`, `viduq1-classic`, `vidu2.0`.
</ParamField>

<ParamField body="subjects" type="array" required>
  Subject array. Multiple subjects are supported. Each subject includes `id` (subject ID), `images` (image URL(s) corresponding to the subject, up to 3 images per subject), and `voice_id` (voice ID, optional).
</ParamField>

<ParamField body="subjects[].id" type="string" required>
  Subject ID. Can be referenced later using `@subject ID` during generation.
</ParamField>

<ParamField body="subjects[].images" type="array" required>
  Subject images. **Note 1**: Image Base64 encoding or image URL is supported. **Note 2**: Supported image formats: png, jpeg, jpg, webp. **Note 3**: Image dimensions must not be smaller than 128\*128, the ratio must be less than 1:4 or 4:1, and the size must not exceed 50M. **Note 4**: The POST body of the HTTP request must not exceed 20MB, and the encoding must include the content-type string, for example: `data:image/png;base64,{base64_encode}`.
</ParamField>

<ParamField body="subjects[].voice_id" type="string">
  Voice ID. Determines the voice timbre in the video. If empty, the system will automatically recommend one. Optional enum values refer to: [New Voice List](https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg), or use the Voice Cloning API to clone any voice timbre; `voice_id` is interoperable.
</ParamField>

<ParamField body="prompt" type="string">
  Text prompt. The text description for video generation. You can reference subjects via `@subject ID`. If the recommended prompt parameter `is_rec` is used, the model will ignore the prompt entered in this parameter.
</ParamField>

<ParamField body="audio" type="boolean">
  Audio/video direct output. `true`: output a video with dialogue and background sound; `false`: output a silent video.
</ParamField>

<ParamField body="voice_id" type="string">
  Voice ID (global). Determines the voice timbre in the video. If empty, the system will automatically recommend one. Note: does not take effect for q3 models.
</ParamField>

<ParamField body="is_rec" type="boolean">
  Whether to use the recommended prompt. `true`: the system automatically recommends a prompt; `false`: generate video based on the input prompt.
</ParamField>

<ParamField body="bgm" type="boolean">
  Background music. `true`: the system will automatically select suitable music from the preset BGM library and add it; `false`: do not add BGM.
</ParamField>

<ParamField body="duration" type="integer">
  Video duration (seconds). `viduq2` series: default 5 seconds, optional 1-10 seconds.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed. If omitted or set to 0, a random number is used; if set manually, the specified seed is used.
</ParamField>

<ParamField body="resolution" type="string">
  Resolution. The default value depends on the model and video duration. `viduq2` (1-10 seconds): default 720p, optional 540p, 720p, 1080p.
</ParamField>

<ParamField body="off_peak" type="boolean">
  Off-peak mode. `true`: generate video during off-peak periods; `false`: generate video immediately.
</ParamField>

<ParamField body="watermark" type="boolean">
  Whether to add a watermark. `true`: add watermark; `false`: do not add watermark.
</ParamField>

<ParamField body="wm_position" type="integer">
  Watermark position. `1`: top-left; `2`: top-right; `3`: bottom-right; `4`: bottom-left.
</ParamField>

<ParamField body="wm_url" type="string">
  Watermark image URL. When not provided, the default watermark `"内容由 AI 生成"` is used.
</ParamField>

<ParamField body="payload" type="string">
  Pass-through parameter. No processing is performed; data transmission only.
</ParamField>

<ParamField body="meta_data" type="string">
  Metadata identifier. JSON-formatted string, pass-through field.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Task ID, used to query the task status.
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Optional values: `processing` (in progress), `failed` (failed), `completed` (completed).
</ResponseField>

<ResponseField name="created_at" type="integer">
  Creation timestamp (Unix timestamp).
</ResponseField>

## Related APIs

* [Vidu Video Overview](./overview)
* [Text-to-Video](./text2video)
* [Image-to-Video](./img2video)
* [Start-End Frame-to-Video](./start-end2video)
* [Query Task](./query)