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

# Unified Video Generation API

> Submit asynchronous generation tasks using the platform's unified video task format, compatible with multiple video models and providers.

# Unified Video Generation API

This is the entry point for multi-vendor video tasks. Requests first enter the unified task protocol, and then the dispatch layer selects the actual channel for execution.

* A single entry point supports both text-to-video and image-to-video.
* Asynchronous processing mode; after a successful submission, a public video task ID is returned.
* Supports passing through vendor-specific parameters via `metadata`.
* Can be used with `/v1/video/generations/{task_id}` and `/v1/videos/{task_id}` to form a complete task flow.

## Method and Path

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

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://www.token-nova.com/v1/video/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1",
      "prompt": "A golden retriever running on the beach, with the camera smoothly tracking it",
      "duration": 5,
      "size": "1280x720",
      "metadata": {
        "style": "cinematic"
      }
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://www.token-nova.com/v1/video/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "kling-v1",
          "prompt": "A golden retriever running on the beach, with the camera smoothly tracking it",
          "duration": 5,
          "size": "1280x720",
          "metadata": {"style": "cinematic"},
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://www.token-nova.com/v1/video/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "kling-v1",
      prompt: "A golden retriever running on the beach, with the camera smoothly tracking it",
      duration: 5,
      size: "1280x720",
      metadata: { style: "cinematic" },
    }),
  });

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

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_task_abc123",
    "task_id": "video_task_abc123",
    "object": "video",
    "model": "kling-v1",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "prompt is required",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid token",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "code": "too_many_requests",
    "message": "The upstream load of the current group is saturated, please try again later",
    "data": null
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "copy_response_body_failed",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response"
    }
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  The model name used for billing and dispatch, such as `kling-v1`, `sora-2`, or `veo-3`. Whether it is ultimately available depends on the current Token's assigned group and channel configuration.
</ParamField>

<ParamField body="prompt" type="string">
  Text prompt. It is usually required for pure text-to-video generation; if you are only making light edits based on an image, it is still recommended to provide a clear description.
</ParamField>

<ParamField body="image" type="string">
  Input image URL or Base64 for image-to-video generation. Together with `images` and `input_reference`, this indicates that visual reference input is present.
</ParamField>

<ParamField body="images" type="array<string>">
  Multi-image reference input. Commonly used for upstreams that require multiple reference images.
</ParamField>

<ParamField body="input_reference" type="string | array<string>">
  Additional reference materials. Some upstreams treat this as the first frame, reference image, or a collection of materials.
</ParamField>

<ParamField body="duration" type="integer">
  Target duration in seconds. Some channels also accept `seconds`; if both are provided, the exact precedence is determined by the adapter.
</ParamField>

<ParamField body="seconds" type="string">
  Duration field in OpenAI video-compatible style. Common values include `5`, `10`, and `15`.
</ParamField>

<ParamField body="size" type="string">
  Size or ratio hint, such as `1280x720`, `720x1280`, or `16:9`. Whether it is recognized depends on the specific channel.
</ParamField>

<ParamField body="metadata" type="object">
  Vendor-specific extension parameters, such as `style`, `negative_prompt`, `camera_control`, `aspectRatio`, and `quality`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Public task ID on the platform. It can be used directly for subsequent queries and proxy downloads.
</ResponseField>

<ResponseField name="task_id" type="string">
  Task ID field retained for compatibility with legacy APIs, usually the same as `id`.
</ResponseField>

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

<ResponseField name="status" type="string">
  Initial status after submission; common values are `queued` or `in_progress`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Task progress percentage. It is usually `0` when first submitted.
</ResponseField>

## Use Cases

### Text-to-Video

```bash theme={null}
curl -X POST https://www.token-nova.com/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "prompt": "A red sports car driving through a rainy night city",
    "seconds": "5"
  }'
```

### Image-to-Video

```bash theme={null}
curl -X POST https://www.token-nova.com/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v1",
    "prompt": "Make the person smile and wave",
    "image": "https://.../portrait.png",
    "duration": 5
  }'
```

## Notes

<Warning>
  This route is a unified task entry point and does not guarantee that all channels accept the same set of parameters. Fields not recognized by the adapter may be ignored, or may only take effect for certain models.
</Warning>

## Related APIs

* [Get Task Status](../tasks/task-status)
* [OpenAI Video-Compatible API](./openai-videos)
* [Upload Image](../uploads/image-upload)