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

# Video Generation

> Generate videos from text prompts, images, or other videos

## Endpoint

```
POST /api/ai/videos/generate
```

Generates videos synchronously. The request blocks until the video is ready, which can take 1-10+ minutes depending on the model and duration.

For long-running or batch generation, consider using the [async queue](/inference-api/reference/async_queue) instead.

## Request Parameters

| Parameter          | Type         | Required   | Default      | Description                                                                                                                                           |
| ------------------ | ------------ | ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string       | **yes**    | --           | Video model name (e.g. `kling-video-v2-6-pro-text-to-video`, `kling-video-o3-pro-reference-to-video`)                                                 |
| `prompt`           | string       | **one of** | --           | Text prompt. Use this or `multi_prompt`, not both.                                                                                                    |
| `multi_prompt`     | array        | **one of** | --           | Multi-shot prompts with per-shot duration. See [Kling O3 Pro reference](/inference-api/reference/models/kling_o3_pro_reference_to_video) for details. |
| `duration`         | integer      | no         | 5            | Video duration in seconds (when using `prompt`).                                                                                                      |
| `aspect_ratio`     | string       | no         | `"16:9"`     | Aspect ratio (e.g. `"16:9"`, `"9:16"`, `"1:1"`).                                                                                                      |
| `input_image`      | string/array | no         | --           | Reference image(s) for image-to-video or reference-to-video models.                                                                                   |
| `input_video`      | string (URL) | no         | --           | Reference video for video-to-video models.                                                                                                            |
| `generate_audio`   | boolean      | no         | `false`      | Generate audio track (model-dependent).                                                                                                               |
| `response_format`  | string       | no         | `"url"`      | `"url"` returns a hosted URL. `"b64_json"` returns base64-encoded video bytes inline.                                                                 |
| `target_namespace` | string       | no         | current user | Namespace to save results and bill to. Can be an organization name.                                                                                   |

Additional parameters vary by model. Use the [model detail endpoint](/inference-api/reference/models/overview#retrieve-model) (`GET /api/ai/models/:id`) to see the `request_schema` for model-specific parameters.

Either `prompt` or `multi_prompt` is required. Sending both returns an error:

```
"Getting model response error: 422 - Value error, Cannot provide both 'prompt' and 'multi_prompt'."
```

Sending neither returns:

```
"Getting model response error: 422 - Value error, Either 'prompt' or 'multi_prompt' must be provided."
```

## Examples

### Basic text-to-video

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://hub.oxen.ai/api/ai/videos/generate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "kling-video-v2-6-pro-text-to-video",
          "prompt": "A red balloon floating upward through blue sky",
          "duration": 5,
      },
  )

  data = response.json()
  print("Video URL:", data["videos"][0]["url"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://hub.oxen.ai/api/ai/videos/generate \
    -H "Authorization: Bearer $OXEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-video-v2-6-pro-text-to-video",
      "prompt": "A red balloon floating upward through blue sky",
      "duration": 5
    }'
  ```
</CodeGroup>

### Response (`response_format: "url"`)

```json theme={null}
{
  "model": "kling-video-v2-6-pro-text-to-video",
  "created": 1775090508,
  "videos": [
    {
      "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."
    }
  ]
}
```

The URL is a temporary link that expires after a period of time.

### Response (`response_format: "b64_json"`)

```json theme={null}
{
  "model": "kling-video-v2-6-pro-text-to-video",
  "created": 1775090508,
  "videos": [
    {
      "b64_json": "<base64-encoded mp4 bytes>"
    }
  ]
}
```

### Multi-shot video

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://hub.oxen.ai/api/ai/videos/generate",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "kling-video-o3-pro-reference-to-video",
          "multi_prompt": [
              {"prompt": "Wide shot: a bird takes off from a branch", "duration": 5},
              {"prompt": "Tracking shot: the bird soars through clouds", "duration": 5},
          ],
          "aspect_ratio": "16:9",
      },
  )

  data = response.json()
  print("Video URL:", data["videos"][0]["url"])
  ```

  ```bash cURL theme={null}
  curl -X POST https://hub.oxen.ai/api/ai/videos/generate \
    -H "Authorization: Bearer $OXEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-video-o3-pro-reference-to-video",
      "multi_prompt": [
        {"prompt": "Wide shot: a bird takes off from a branch", "duration": 5},
        {"prompt": "Tracking shot: the bird soars through clouds", "duration": 5}
      ],
      "aspect_ratio": "16:9"
    }'
  ```
</CodeGroup>

## Important Notes

* Video generation can take several minutes. Very long generations may time out on your client side.
* For long-running or batch generation, use [`/ai/queue`](/inference-api/reference/async_queue) which returns immediately and processes in the background.

## Errors

| Condition                           | Error                                                                                                    |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Both `prompt` and `multi_prompt`    | `"Getting model response error: 422 - Value error, Cannot provide both 'prompt' and 'multi_prompt'."`    |
| Neither `prompt` nor `multi_prompt` | `"Getting model response error: 422 - Value error, Either 'prompt' or 'multi_prompt' must be provided."` |
| Model not found                     | `"Model not found: <name>"`                                                                              |