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

# OpenAI 视频兼容接口

> 使用 OpenAI Videos 风格的创建、查询、remix 和内容代理路由操作视频任务。

# OpenAI 视频兼容接口

这组路由对外表现为 OpenAI Videos API 风格，适合已经按 `video` 对象读写结果的客户端。

* 创建、查询和 remix 统一使用 OpenAI 风格 `video` 对象。
* 公开 `id` 会映射到平台任务 ID，而不是直接暴露上游原始任务 ID。
* `content` 代理路由支持 API Key 和登录态访问。
* Remix 会优先回查原视频任务并锁定到原始渠道执行。

## 路由清单

| Method | Path                           | 说明              |
| ------ | ------------------------------ | --------------- |
| `POST` | `/v1/videos`                   | 创建视频任务          |
| `GET`  | `/v1/videos/{task_id}`         | 查询视频任务          |
| `POST` | `/v1/videos/{video_id}/remix`  | 基于已有视频任务做 remix |
| `GET`  | `/v1/videos/{task_id}/content` | 代理下载视频内容        |

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://www.token-nova.com/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "一架纸飞机穿过明亮办公室，镜头平滑跟随",
      "seconds": "5",
      "size": "1280x720"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://www.token-nova.com/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "sora-2",
          "prompt": "一架纸飞机穿过明亮办公室，镜头平滑跟随",
          "seconds": "5",
          "size": "1280x720",
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://www.token-nova.com/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "sora-2",
      prompt: "一架纸飞机穿过明亮办公室，镜头平滑跟随",
      seconds: "5",
      size: "1280x720",
    }),
  });

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

## 响应示例

<ResponseExample>
  ```json 200 - 创建成功 theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "sora-2",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "seconds": "5",
    "size": "1280x720"
  }
  ```

  ```json 200 - 查询成功 theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "sora-2",
    "status": "completed",
    "progress": 100,
    "created_at": 1735689600,
    "completed_at": 1735689900,
    "video_url": "https://...",
    "seconds": "5",
    "size": "1280x720"
  }
  ```

  ```json 200 - 查询失败任务 theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "sora-2",
    "status": "failed",
    "progress": 100,
    "created_at": 1735689600,
    "error": {
      "message": "Content policy violation",
      "code": "content_policy"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "message": "task_origin_not_exist",
      "type": "new_api_error",
      "param": "",
      "code": "task_not_exist"
    }
  }
  ```
</ResponseExample>

## 认证

创建、查询、remix 使用 Bearer Token：

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

`GET /v1/videos/{task_id}/content` 同时支持：

* `Authorization: Bearer YOUR_API_KEY`
* Web 仪表盘登录态 `UserAuth`

## Path Parameters

<ParamField body="task_id" type="string" required>
  视频任务 ID，用于查询和内容代理。
</ParamField>

<ParamField body="video_id" type="string" required>
  Remix 的源视频 ID。服务端会先用它回查原任务和原渠道。
</ParamField>

## Body

<ParamField body="model" type="string" required>
  视频模型名称，例如 `sora-2`、`sora_video2` 或其他渠道映射后的模型名。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频描述或 remix 指令。
</ParamField>

<ParamField body="image" type="string">
  图生视频输入图。是否支持取决于具体上游。
</ParamField>

<ParamField body="seconds" type="string">
  目标视频时长，常见值为 `5`、`10`、`15`。
</ParamField>

<ParamField body="size" type="string">
  目标分辨率或比例，例如 `1280x720`、`720x1280`、`16:9`。
</ParamField>

<ParamField body="metadata" type="object">
  供应商透传参数。Remix 时也可以放入上游专有字段。
</ParamField>

## Response

<ResponseField name="id" type="string">
  公开视频任务 ID。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态，常见值为 `queued`、`in_progress`、`completed`、`failed`。
</ResponseField>

<ResponseField name="video_url" type="string">
  生成完成后的可播放地址。很多情况下会指向平台代理路由。
</ResponseField>

<ResponseField name="error" type="object">
  失败任务的错误详情，仅在 `status = failed` 时出现。
</ResponseField>

## 使用场景

### 查询任务

```bash theme={null}
curl https://www.token-nova.com/v1/videos/video_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Remix

```bash theme={null}
curl -X POST https://www.token-nova.com/v1/videos/video_abc123/remix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "保持构图，把画面改成夜晚霓虹灯风格"
  }'
```

### 代理下载

```bash theme={null}
curl -L https://www.token-nova.com/v1/videos/video_abc123/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output output.mp4
```

## 注意事项

<Tip>
  如果你同时接入了 `/v1/video/generations` 和 `/v1/videos`，建议前端固定选择一种返回结构使用，不要在同一套解析逻辑里混用通用任务包装和 OpenAI `video` 对象。
</Tip>

## 相关接口

* [统一视频生成接口](./video-generations)
* [获取任务状态](../tasks/task-status)
* [账户余额与用量](../account/billing)