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

# Veo Video Generation

> Use `POST /v1/videos` to call the Veo model and submit asynchronous video tasks.

# Veo Video Generation

OpenAI-format entry point. If you need to use the unified video `POST /v1/video/create`, please see [Create Video](./unified-generation).

The Veo series is currently submitted through `POST /v1/videos`, with JSON submission as the primary method.

* The routing entry point is `POST /v1/videos`.
* The current models are only `veo_3_1` and `veo_3_1-fast`.
* Currently, `size` will be converted and submitted together with `metadata.output_config.resolution` and `aspect_ratio`.
* Reference images are still expressed by `input_reference`, but in JSON requests they are usually represented as a URL, base64, or Data URL.

## Current Models

* `veo_3_1`
* `veo_3_1-fast`

## Method and Path

```http theme={null}
POST /v1/videos
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo_3_1-fast",
      "prompt": "Dance in the center of the square",
      "size": "720x1280",
      "seconds": "8",
      "input_reference": "data:image/png;base64,BASE64_IMAGE",
      "metadata": {
        "output_config": {
          "aspect_ratio": "9:16",
          "audio_generation": "Disabled",
          "resolution": "720P"
        }
      }
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "veo_3_1-fast",
          "prompt": "Dance in the center of the square",
          "size": "720x1280",
          "seconds": "8",
          "input_reference": "data:image/png;base64,BASE64_IMAGE",
          "metadata": {
              "output_config": {
                  "aspect_ratio": "9:16",
                  "audio_generation": "Disabled",
                  "resolution": "720P",
              }
          },
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "veo_3_1-fast",
      prompt: "Dance in the center of the square",
      size: "720x1280",
      seconds: "8",
      input_reference: "data:image/png;base64,BASE64_IMAGE",
      metadata: {
        output_config: {
          aspect_ratio: "9:16",
          audio_generation: "Disabled",
          resolution: "720P",
        },
      },
    }),
  });

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

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_abc123",
    "object": "video",
    "model": "veo_3_1-fast",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "seconds": "8",
    "size": "720x1280"
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. Currently only `veo_3_1` and `veo_3_1-fast` are organized.
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt.
</ParamField>

<ParamField body="size" type="string">
  Size string. Common values currently include `720x1280` or `1280x720`, which are used to derive Veo's resolution and aspect ratio.
</ParamField>

<ParamField body="seconds" type="string | integer">
  Target duration. Currently submitted through `seconds`; the gateway also supports `duration` and `metadata.durationSeconds`.
</ParamField>

<ParamField body="input_reference" type="string | array<string>">
  Reference image input. JSON requests can currently use a URL, base64, or data URI; the Veo adapter layer also supports multipart file uploads.
</ParamField>

<ParamField body="metadata" type="object">
  Extended configuration. The Veo pipeline will continue parsing `metadata` into upstream Veo fields such as `DurationSeconds`, `AspectRatio`, and `Resolution`.
</ParamField>

<ParamField body="enable_upsample" type="boolean">
  This is the Apifox field reference you provided, but based on the current main repository pipeline, it is not an explicit top-level field in the generic Veo DTO. If you want to express clarity or resolution, `size` and `metadata` are currently recommended instead.
</ParamField>

## Current Rules

| Item                    | Rule                                                                         |
| ----------------------- | ---------------------------------------------------------------------------- |
| Request format          | JSON                                                                         |
| Reference image format  | Supports URL, base64, and data URI, and also supports multipart files        |
| Reference-to-video mode | The aspect ratio will be forcibly constrained to `16:9`                      |
| Parameter mapping       | `size` will be further mapped to Veo-required `resolution` and `aspectRatio` |

## Related Endpoints

* [Veo Video Overview](./overview)
* [Veo Task Query](./query)
* [Video Remix](./remix)
* [Create Video (Unified Video)](./unified-generation)