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

# Kling Video Generation

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

# Kling Video Generation

Kling uses `POST /v1/videos` to submit tasks, with JSON submission as the primary method.

* The route entry is `POST /v1/videos`.
* JSON submission is currently used.
* Supports multiple scenarios, including text-to-video, image-to-video, and first-and-last-frame video generation.
* Extended parameters, including output configuration and scenario type, are passed through the `metadata` field.
* After a successful submission, the task `id` and `status` are returned, and the result is later polled via [Task Status Query](./query).

## Supported Models

* `Kling-3.0-Omni`: Kling 3.0 all-in-one version
* `Kling-2.6`: Kling 2.6 version
* `Kling-2.5`: Kling 2.5 version

## 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": "Kling-3.0-Omni",
      "prompt": "Cyberpunk city night scene, the camera slowly pushes in",
      "seconds": "5",
      "metadata": {
        "output_config": {
          "resolution": "720P",
          "aspect_ratio": "16:9"
        }
      }
    }'
  ```

  ```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": "Kling-3.0-Omni",
          "prompt": "Cyberpunk city night scene, the camera slowly pushes in",
          "seconds": "5",
          "metadata": {
              "output_config": {
                  "resolution": "720P",
                  "aspect_ratio": "16:9",
              }
          },
      },
      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: "Kling-3.0-Omni",
      prompt: "Cyberpunk city night scene, the camera slowly pushes in",
      seconds: "5",
      metadata: {
        output_config: {
          resolution: "720P",
          aspect_ratio: "16:9",
        },
      },
    }),
  });

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

## Scenario Examples

### Text-to-Video

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "Cyberpunk city night scene, the camera slowly pushes in",
  "seconds": "5",
  "metadata": {
    "output_config": {
      "resolution": "720P",
      "aspect_ratio": "16:9"
    }
  }
}
```

### Image-to-Video

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "Make the character walk forward and smile",
  "image": "https://example.com/character.png",
  "seconds": "5",
  "metadata": {
    "output_config": {
      "resolution": "1080P",
      "aspect_ratio": "9:16"
    }
  }
}
```

### First-and-Last-Frame Video Generation

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "In a silent system space, the character is illuminated by a blue panel",
  "seconds": "15",
  "size": "720x1280",
  "metadata": {
    "output_config": {
      "duration": 15,
      "resolution": "720P",
      "aspect_ratio": "9:16",
      "audio_generation": "Enabled"
    },
    "last_frame_url": "https://example.com/last-frame.png"
  }
}
```

### Motion Control

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "The character waves hello",
  "image": "https://example.com/character.png",
  "seconds": "5",
  "metadata": {
    "scene_type": "motion_control",
    "motion_level": "pro",
    "output_config": {
      "resolution": "1080P",
      "aspect_ratio": "16:9"
    }
  }
}
```

## Response Example

> **Note**: The `model` field in the response may include a billing-spec suffix (such as `720p-ref-audio`), which differs from the model name passed in the request.

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_123",
    "task_id": "video_123",
    "object": "video",
    "model": "kling-3.0-omni-720p-ref-audio",
    "status": "queued",
    "progress": 0,
    "created_at": 1712697600
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. For example, `Kling-3.0-Omni`, `Kling-2.6`, `Kling-2.5`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt. The text description for video generation, supporting both Chinese and English.
</ParamField>

<ParamField body="seconds" type="string">
  Video duration. For example, `5`, `10`, `15`.
</ParamField>

<ParamField body="size" type="string">
  Video size. Fast size input, for example `720x1280`.
</ParamField>

<ParamField body="image" type="string">
  Reference image. Reference image URL.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata. A container for extended parameters. It is recommended to place all upstream native parameters in `metadata`.
</ParamField>

<ParamField body="metadata.output_config" type="object">
  Output configuration. It is recommended to place all native parameters in `output_config`.

  * `duration`: duration (seconds)
  * `resolution`: resolution (`720P`, `1080P`)
  * `aspect_ratio`: aspect ratio (`16:9`, `9:16`, `1:1`)
  * `audio_generation`: audio generation (`Enabled`, `Disabled`)
</ParamField>

<ParamField body="metadata.scene_type" type="string">
  Scene type. Examples: `motion_control` (motion control), `avatar_i2v` (digital human generation), `lip_sync` (lip sync), `template_effect` (template effects).
</ParamField>

<ParamField body="metadata.motion_level" type="string">
  Motion level. Examples: `std` (standard), `pro` (professional, used for motion control billing tiers).
</ParamField>

<ParamField body="metadata.offpeak" type="boolean">
  Whether off-peak billing is used. `true`: generate video off-peak; `false`: generate video immediately.
</ParamField>

<ParamField body="metadata.last_frame_url" type="string">
  Last frame in first-and-last-frame generation. Specify the tail-frame image URL when generating a first-and-last-frame video.
</ParamField>

<ParamField body="metadata.video_url" type="string">
  Reference video URL.
</ParamField>

<ParamField body="metadata.file_infos" type="string">
  File information. Native `FileInfos` passthrough (advanced usage).
</ParamField>

<ParamField body="metadata.ext_info" type="string">
  Extended information. Native `ExtInfo` string passthrough (advanced usage).
</ParamField>

## Response

<ResponseField name="id" type="string">
  Task ID.
</ResponseField>

<ResponseField name="task_id" type="string">
  Task ID (same as `id`).
</ResponseField>

<ResponseField name="object" type="string">
  Fixed to `video`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name.
</ResponseField>

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

<ResponseField name="progress" type="integer">
  Progress percentage (0-100).
</ResponseField>

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

## Related APIs

* [Kling Video Overview](./overview)
* [Task Status Query](./query)