> ## 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 Veo asynchronous generation tasks through a unified video format.

# Create Video

The Veo unified video entry point uses `POST /v1/video/create`, and the request body is JSON. Unlike [OpenAI-format Veo video generation](./generation), this endpoint uses fields such as `images`, `orientation`, and `aspect_ratio` to represent reference images and aspect ratio.

* The route entry point is `POST /v1/video/create`.
* Reference images are passed as a list of URLs through the `images` array.
* Common model examples include `veo3.1-fast-components`; use the models actually available in the current channel as the reference.
* After a successful submission, a task object containing `id`, `status`, and `progress` is returned. Use [Query Task](./unified-query) to poll for the result afterward.

## 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" \
    -H "Accept: application/json" \
    -d '{
      "prompt": "The cow flew into the sky",
      "model": "veo3.1-fast-components",
      "images": [
        "https://example.com/frame-1.png",
        "https://example.com/frame-2.png"
      ],
      "orientation": "landscape",
      "size": "1280x720",
      "duration": 8,
      "aspect_ratio": "16:9",
      "enable_upsample": false
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/video/create",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "prompt": "The cow flew into the sky",
          "model": "veo3.1-fast-components",
          "images": [
              "https://example.com/frame-1.png",
              "https://example.com/frame-2.png",
          ],
          "orientation": "landscape",
          "size": "1280x720",
          "duration": 8,
          "aspect_ratio": "16:9",
          "enable_upsample": False,
      },
      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",
      Accept: "application/json",
    },
    body: JSON.stringify({
      prompt: "The cow flew into the sky",
      model: "veo3.1-fast-components",
      images: [
        "https://example.com/frame-1.png",
        "https://example.com/frame-2.png",
      ],
      orientation: "landscape",
      size: "1280x720",
      duration: 8,
      aspect_ratio: "16:9",
      enable_upsample: false,
    }),
  });

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

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_8b8232a3-847b-40e2-a3a3-912813b7ac60",
    "object": "video",
    "model": "veo3.1-fast-components",
    "status": "queued",
    "progress": 0,
    "created_at": 1768489641,
    "size": "1280x720",
    "detail": {
      "input": {
        "aspect_ratio": "16:9",
        "images": [
          "https://example.com/frame-1.png",
          "https://example.com/frame-2.png"
        ],
        "model": "veo3.1-fast-components",
        "prompt": "The cow flew into the sky"
      }
    },
    "status_update_time": 1768489641
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="images" type="array" required>
  An array of image URLs. Pass a list of reference image URLs.
</ParamField>

<ParamField body="model" type="string" required>
  The model name. For example, `veo3.1-fast-components`.
</ParamField>

<ParamField body="orientation" type="string" required>
  The frame orientation. `portrait` means vertical, and `landscape` means horizontal.
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt. The text describing the video content.
</ParamField>

<ParamField body="size" type="string" required>
  Output size. Defaults to `720x1280`. Available values: `720x1280`, `1280x720`.
</ParamField>

<ParamField body="duration" type="integer" required>
  Video duration in seconds. Veo defaults to 8 seconds.
</ParamField>

<ParamField body="aspect_ratio" type="string" required>
  Aspect ratio. `16:9` or `9:16`.
</ParamField>

<ParamField body="enable_upsample" type="boolean">
  Whether to enable HD upsampling (landscape only).
</ParamField>

## Response

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

<ResponseField name="object" type="string">
  Object type, commonly `video`.
</ResponseField>

<ResponseField name="model" type="string">
  The actual model used.
</ResponseField>

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

<ResponseField name="progress" type="integer">
  Task progress percentage.
</ResponseField>

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

<ResponseField name="size" type="string">
  Output size.
</ResponseField>

<ResponseField name="detail" type="object">
  Submission details, usually containing the echoed `input` field.
</ResponseField>

<ResponseField name="status_update_time" type="integer">
  Most recent status update time (Unix timestamp).
</ResponseField>

## Related APIs

* [Veo Video Overview](./overview)
* [Query Task](./unified-query)
* [Veo Video Generation (OpenAI Format)](./generation)