> ## 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.

# Create Video

> Use `POST /v1/video/create` to submit Vidu asynchronous generation tasks through the unified video format.

# Create Video

The Vidu unified video entry uses `POST /v1/video/create`, and the request body is JSON. Unlike the [official Vidu format](./text2video), this endpoint uses fields such as `images`, `aspect_ratio`, `resolution`, and `duration`.

* The route endpoint is `POST /v1/video/create`.
* Reference images are passed as a URL list through the `images` array; text-to-video can pass an empty array.
* A common model example is `viduq3-pro`; use the actually available model for the current channel as the reference.
* After a successful submission, the task `id` and `status` are returned, and you can later use [Query Task](./unified-query) to poll for results.

## Supported Models

* `viduq3-pro`: Efficiently generates high-quality audio and video content, making video content more vivid, more lifelike, and more three-dimensional
* `viduq2-pro-fast`: Lower price floor, stable results, generation speed 2-3 times faster than viduq2-turbo
* `viduq2-pro`: New model, good results, rich details
* `viduq2-turbo`: New model, good results, fast generation
* `viduq1`: Clear visuals, smooth transitions, stable camera movement
* `viduq1-classic`: Clear visuals, richer transitions and camera movement
* `vidu2.0`: Fast generation speed

## Method and Path

```http theme={null}
POST /v1/video/create
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/video/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "viduq3-pro",
      "prompt": "一只猫在草地上追逐蝴蝶",
      "aspect_ratio": "16:9",
      "duration": 5,
      "audio": false,
      "images": []
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/video/create",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "viduq3-pro",
          "prompt": "一只猫在草地上追逐蝴蝶",
          "aspect_ratio": "16:9",
          "duration": 5,
          "audio": False,
          "images": [],
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/video/create", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "viduq3-pro",
      prompt: "一只猫在草地上追逐蝴蝶",
      aspect_ratio: "16:9",
      duration: 5,
      audio: false,
      images: [],
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "created_at": "2025-11-08T23:07:57.510141923+08:00",
    "status": "processing",
    "task_id": "48038932-0ff5-4251-8b4b-7a76c09fd114"
  }
  ```
</ResponseExample>

## Authentication

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

## Body

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

<ParamField body="images" type="array" required>
  Image array. Supports passing image Base64-encoded data or image URLs (ensure they are accessible). For text-to-video, pass an empty array `[]`; for image-to-video, pass 1 image; for first-and-last-frame video generation, pass 2 images. Supported image formats are png, jpeg, jpg, and webp. The aspect ratio must be less than 1:4 or greater than 4:1, and the size must not exceed 50 MB.
</ParamField>

<ParamField body="prompt" type="string">
  Text prompt. The text description for the generated video, with a maximum length of 2000 characters. If you use the `is_rec` recommended prompt parameter, the model will ignore the prompt input in this parameter.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio. Default is `16:9`. Optional values: `16:9`, `9:16`, `3:4`, `4:3`, `1:1`. Note: `3:4` and `4:3` are supported only by q2 and q3 models.
</ParamField>

<ParamField body="audio" type="boolean">
  Whether to use direct audio-video output capability. Default is `false`. `false`: audio-video direct output is not needed, and a silent video is output; `true`: audio-video direct output is needed, and a video with dialogue and background sound is output.
</ParamField>

<ParamField body="voice_id" type="string">
  Voice ID. Does not take effect for q3 models. Used to determine the voice timbre in the video; if empty, the system will recommend one automatically.
</ParamField>

<ParamField body="is_rec" type="boolean">
  Whether to use recommended prompts. `true`: yes, the system automatically recommends prompts and generates the video using the prompt content, with the number of recommended prompts = 1; `false`: no, generate the video based on the input prompt.
</ParamField>

<ParamField body="bgm" type="boolean">
  Whether to add background music to the generated video. Default is `false`. `true`: the system will automatically select suitable music from the preset BGM library and add it; `false`: no BGM is added.
</ParamField>

<ParamField body="duration" type="integer">
  Video duration (seconds). The default for the `viduq2` series is 5. Optional: 1-10.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed. When omitted by default or set to 0, a random number will be used instead. If manually set, the specified seed will be used.
</ParamField>

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

<ParamField body="payload" type="string">
  Passthrough parameter. No processing is performed; data transmission only. Maximum length: 1048576 characters.
</ParamField>

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

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

<ParamField body="wm_position" type="integer">
  Watermark position. Default is `3` (bottom right). Optional values: `1`: top left; `2`: top right; `3`: bottom right; `4`: bottom left.
</ParamField>

<ParamField body="wm_url" type="string">
  Watermark content, where this is an image URL. If not provided, the default watermark is used: content generated by AI.
</ParamField>

<ParamField body="meta_data" type="string">
  Metadata identifier. A JSON-formatted string, passed through as-is.
</ParamField>

## Response

<ResponseField name="created_at" type="string">
  Creation time (ISO 8601 format).
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Common values include `processing`, `failed`, and `completed`.
</ResponseField>

<ResponseField name="task_id" type="string">
  Task ID, passed as the `id` parameter in subsequent queries.
</ResponseField>

## Related APIs

* [Vidu Video Overview](./overview)
* [Query Task](./unified-query)
* [Vidu Text-to-Video (Official Format)](./text2video)