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

# 视频通用说明

> 用 OpenAI 兼容的 Videos 接口调用可灵视频：提交任务、查询进度、下载视频，以及各型号参数与计费。

## 流程

视频生成是**异步任务**，分三步：

1. `POST /v1/videos` 提交任务，拿到任务 `id`。
2. `GET /v1/videos/{id}` 轮询进度，直到 `status` 为 `completed` 或 `failed`。
3. `GET /v1/videos/{id}/content` 下载 MP4。

一条视频通常需要 1–5 分钟。建议每 10–15 秒查询一次，不要高频轮询。

所有请求都使用 `Authorization: Bearer YOUR_API_KEY` 认证。

## 提交任务

```text theme={null}
POST https://token.poryf.com/v1/videos
```

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型 ID，例如 `kling-3.0` |
| `prompt` | string | 文生视频必填 | 画面与运动描述 |
| `seconds` | integer | 否 | 时长（秒），默认 5，范围见下表 |
| `resolution` | string | 否 | `720P` 或 `1080P`，默认 `720P` |
| `aspect_ratio` | string | 否 | `16:9`、`9:16`、`1:1`；只对文生视频生效 |
| `size` | string | 否 | 也可用 `1280x720` 这类尺寸代替 `resolution` + `aspect_ratio` |
| `audio` | boolean | 否 | 是否同步生成音频，默认 `false`；仅部分型号支持 |
| `input_reference` | string / array | 图生视频必填 | 首帧图片 URL；传两张时，第一张为首帧，第二张为尾帧 |
| `negative_prompt` | string | 否 | 不希望出现的内容 |
| `seed` | integer | 否 | 随机种子 |

<Warning>
  首帧、尾帧只接受公网可访问的 `http(s)` 图片 URL，不支持上传文件或 Base64。图生视频的画面比例跟随首帧图片，此时 `aspect_ratio` 不生效。
</Warning>

### 各型号参数

| 模型 ID | 时长 | 分辨率 | 有声 |
| - | - | - | - |
| `kling-3.0` | 3–15 秒 | 720P / 1080P | 支持 |
| `kling-3.0-omni` | 3–15 秒 | 720P / 1080P | 支持 |
| `kling-2.6` | 3–15 秒 | 720P / 1080P | 仅 1080P 支持 |
| `kling-3.0-turbo` | 3–15 秒 | 720P / 1080P | 不支持 |
| `kling-o1` | 3–15 秒 | 720P / 1080P | 不支持 |
| `kling-2.5` | 5 或 10 秒 | 720P / 1080P | 不支持 |

所有型号都支持文生视频，以及首帧 / 首尾帧图生视频。

### 示例：文生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "清晨的海边，一只柯基在沙滩上奔跑，镜头缓慢跟随",
    "seconds": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9"
  }'
```

### 示例：首尾帧图生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "花朵从含苞到完全绽放",
    "seconds": 5,
    "input_reference": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }'
```

提交成功后返回任务对象（示例结构）：

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "queued",
  "progress": 0
}
```

## 查询进度

```text theme={null}
GET https://token.poryf.com/v1/videos/{id}
```

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

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "seconds": "5"
}
```

| `status` | 含义 |
| - | - |
| `queued` | 排队中 |
| `in_progress` | 生成中；`progress` 为 0–100 的进度 |
| `completed` | 已完成，可以下载 |
| `failed` | 失败；`error.message` 给出原因，费用自动退回 |

失败时的响应示例：

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "failed",
  "progress": 100,
  "error": { "code": "task_failed", "message": "..." }
}
```

## 下载视频

```text theme={null}
GET https://token.poryf.com/v1/videos/{id}/content
```

```bash theme={null}
curl -L https://token.poryf.com/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o video.mp4
```

返回 MP4 文件内容。

<Warning>
  视频约 7 天内可以下载。过期后接口返回 `410`，错误码为 `artifact_gone`，无法再取回。请在任务完成后及时下载，转存到自己的存储。
</Warning>

## 计费

* 按秒计费，按分辨率和是否有声分档，费用为「单价 × 时长」。
* 提交任务时按请求的时长、分辨率预扣费用；任务失败后自动全额退回。
* 各型号的实时单价见 [模型广场](https://token.poryf.com/pricing)，更多说明见 [价格说明](/usage)。

## 常见错误

| 错误信息 | 原因 |
| - | - |
| `prompt or input_reference is required` | 既没有 `prompt`，也没有首帧图片 |
| `seconds must be an integer between 3 and 15` | 时长超出范围 |
| `seconds must be one of 5, 10` | `kling-2.5` 只支持 5 秒或 10 秒 |
| `resolution must be one of 720P, 1080P` | 分辨率不支持 |
| `aspect_ratio must be one of ...` | 比例不支持 |
| `this model does not generate audio` | 该型号不支持有声 |
| `audio requires 1080P for this model` | `kling-2.6` 有声需要 1080P |
| `at most two images are supported ...` | 图片超过两张（首帧 + 尾帧） |
| `input_reference must be an HTTP(S) URL ...` | 图片不是 URL，或传了文件 / Base64 |

其他错误见 [排错指南](/errors)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.