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

# 统一视频生成接口

> 使用平台统一视频任务格式提交异步生成任务，适配多家视频模型和供应商。

# 统一视频生成接口

这是面向多供应商的视频任务入口。请求先进入统一任务协议，再由分发层选择实际渠道执行。

* 一个入口同时支持文生视频和图生视频。
* 异步处理模式，提交成功后返回公开视频任务 ID。
* 支持通过 `metadata` 透传供应商专有参数。
* 可与 `/v1/video/generations/{task_id}` 和 `/v1/videos/{task_id}` 组成完整任务链路。

## 方法与路径

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

## 请求示例

<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": "一只金毛犬在海滩上奔跑，镜头平滑跟随",
      "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": "一只金毛犬在海滩上奔跑，镜头平滑跟随",
          "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: "一只金毛犬在海滩上奔跑，镜头平滑跟随",
      duration: 5,
      size: "1280x720",
      metadata: { style: "cinematic" },
    }),
  });

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

## 响应示例

<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": "无效的令牌",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "code": "too_many_requests",
    "message": "当前分组上游负载已饱和，请稍后再试",
    "data": null
  }
  ```

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

## 认证

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

## Body

<ParamField body="model" type="string" required>
  计费和分发使用的模型名，例如 `kling-v1`、`sora-2`、`veo-3`。最终是否可用取决于当前 Token 所属分组和渠道配置。
</ParamField>

<ParamField body="prompt" type="string">
  文本提示词。纯文生视频时通常必填；如果只做基于图片的轻改动，仍建议提供明确描述。
</ParamField>

<ParamField body="image" type="string">
  图生视频输入图片 URL 或 Base64。与 `images`、`input_reference` 一起表示存在视觉参考输入。
</ParamField>

<ParamField body="images" type="array<string>">
  多图参考输入。常用于兼容需要多参考图的上游。
</ParamField>

<ParamField body="input_reference" type="string | array<string>">
  额外参考素材。部分上游会把它当作首帧、参考图或素材集合。
</ParamField>

<ParamField body="duration" type="integer">
  目标时长，单位为秒。部分渠道也接受 `seconds`，若两者同时提供，具体优先级由适配器决定。
</ParamField>

<ParamField body="seconds" type="string">
  OpenAI 视频兼容风格的时长字段。常见值如 `5`、`10`、`15`。
</ParamField>

<ParamField body="size" type="string">
  尺寸或比例提示，例如 `1280x720`、`720x1280`、`16:9`。是否识别由具体渠道决定。
</ParamField>

<ParamField body="metadata" type="object">
  供应商专有扩展参数，例如 `style`、`negative_prompt`、`camera_control`、`aspectRatio`、`quality`。
</ParamField>

## Response

<ResponseField name="id" type="string">
  平台公开任务 ID。后续可直接用于查询和代理下载。
</ResponseField>

<ResponseField name="task_id" type="string">
  兼容旧接口保留的任务 ID 字段，通常与 `id` 相同。
</ResponseField>

<ResponseField name="object" type="string">
  固定为 `video`。
</ResponseField>

<ResponseField name="status" type="string">
  提交后的初始状态，常见值为 `queued` 或 `in_progress`。
</ResponseField>

<ResponseField name="progress" type="integer">
  任务进度百分比。刚提交时通常为 `0`。
</ResponseField>

## 使用场景

### 文生视频

```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": "一辆红色跑车在雨夜城市中穿行",
    "seconds": "5"
  }'
```

### 图生视频

```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": "让人物微笑并挥手",
    "image": "https://.../portrait.png",
    "duration": 5
  }'
```

## 注意事项

<Warning>
  这个路由是统一任务入口，不保证所有渠道都接受同一组参数。未在适配器中识别的字段可能被忽略，也可能只对某些模型生效。
</Warning>

## 相关接口

* [获取任务状态](../tasks/task-status)
* [OpenAI 视频兼容接口](./openai-videos)
* [上传图片](../uploads/image-upload)