> ## 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-Compatible Video Interface

> Use OpenAI Videos-style create, query, remix, and content proxy routing operations for video tasks.

# OpenAI-Compatible Video Interface

This set of routes presents itself externally in an OpenAI Videos API style, suitable for clients that already read and write results as `video` objects.

* Creation, querying, and remix all use the OpenAI-style `video` object.
* The exposed `id` maps to the platform task ID, rather than directly exposing the upstream raw task ID.
* The `content` proxy route supports access via API Key and logged-in session state.
* Remix will preferentially look up the original video task and lock execution to the original channel.

## Route List

| Method | Path                           | Description                           |
| ------ | ------------------------------ | ------------------------------------- |
| `POST` | `/v1/videos`                   | Create a video task                   |
| `GET`  | `/v1/videos/{task_id}`         | Query a video task                    |
| `POST` | `/v1/videos/{video_id}/remix`  | Remix based on an existing video task |
| `GET`  | `/v1/videos/{task_id}/content` | Proxy download of video content       |

## Request Examples

<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": "A paper airplane flies through a bright office, with the camera smoothly following",
      "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": "A paper airplane flies through a bright office, with the camera smoothly following",
          "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: "A paper airplane flies through a bright office, with the camera smoothly following",
      seconds: "5",
      size: "1280x720",
    }),
  });

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

## Response Examples

<ResponseExample>
  ```json 200 - Created successfully 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 - Query successful 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 - Failed query task 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>

## Authentication

Creation, querying, and remix use Bearer Token:

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

`GET /v1/videos/{task_id}/content` also supports:

* `Authorization: Bearer YOUR_API_KEY`
* Web dashboard login state `UserAuth`

## Path Parameters

<ParamField body="task_id" type="string" required>
  Video task ID, used for querying and content proxying.
</ParamField>

<ParamField body="video_id" type="string" required>
  The source video ID for remix. The server will first look up the original task and original channel using it.
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Video model name, such as `sora-2`, `sora_video2`, or a model name mapped from another channel.
</ParamField>

<ParamField body="prompt" type="string" required>
  Video description or remix instruction.
</ParamField>

<ParamField body="image" type="string">
  Input image for image-to-video generation. Support depends on the specific upstream provider.
</ParamField>

<ParamField body="seconds" type="string">
  Target video duration, common values are `5`, `10`, and `15`.
</ParamField>

<ParamField body="size" type="string">
  Target resolution or ratio, such as `1280x720`, `720x1280`, or `16:9`.
</ParamField>

<ParamField body="metadata" type="object">
  Vendor passthrough parameters. For remix, upstream proprietary fields can also be included here.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Public video task ID.
</ResponseField>

<ResponseField name="status" type="string">
  Task status, common values are `queued`, `in_progress`, `completed`, and `failed`.
</ResponseField>

<ResponseField name="video_url" type="string">
  Playable URL after generation is complete. In many cases, it points to the platform proxy route.
</ResponseField>

<ResponseField name="error" type="object">
  Error details for failed tasks, shown only when `status = failed`.
</ResponseField>

## Usage Scenarios

### Query a Task

```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": "Keep the composition, but change the scene to a neon-lit nighttime style"
  }'
```

### Proxy Download

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

## Notes

<Tip>
  If you have both `/v1/video/generations` and `/v1/videos` integrated, it is recommended that the frontend consistently choose one response structure to use, and avoid mixing the generic task wrapper and the OpenAI `video` object within the same parsing logic.
</Tip>

## Related APIs

* [Unified Video Generation API](./video-generations)
* [Get Task Status](../tasks/task-status)
* [Account Balance and Usage](../account/billing)