# Kling 4.0 — /videos/generations

Kling 4.0 是快手可灵的新一代视频模型。通过 `POST /v1/videos/generations` 提交异步任务：不带素材为文生视频，也可以同时传最多 10 张参考图、5 段参考视频和 3 段参考音频。时长 3–30 秒，720P / 1080P，16:9 或 9:16，成片自带声音。按秒计费，带参考视频时计费秒数 = 输出秒数 + 参考视频秒数。

**端点:** `POST https://nezhagate.com/v1/videos/generations`

## 快速开始

三步跑通：提交任务 → 查询结果 → 拿到视频链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

**第 1 步 · 提交任务（立刻返回任务号，HTTP 202）**

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-4.0", "prompt": "一位舞者在飘落的枫叶中旋转，镜头环绕她缓缓移动", "duration": 5, "resolution": "720P", "size": "16:9"}'
```

返回（HTTP 202）

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-4.0"
}
```

**第 2 步 · 每 5–10 秒查询一次，直到 `status` 变成 `succeeded` 或 `failed`**

```
curl https://nezhagate.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功时的返回

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-4.0",
  "data": [
    {"url": "https://img.nezhagate.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "kling-4.0"}
}
```

**第 3 步 · `data[0].url` 就是成片（MP4），保留 15 天；需要长期使用，请下载到你自己的存储。**

**完整示例（Python：提交 → 等待 → 保存到本地）**

```
import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "kling-4.0",
    "prompt": "一位舞者在飘落的枫叶中旋转，镜头环绕她缓缓移动",
    "duration": 5,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 10 秒查询一次，最多等一小时
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载视频
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-4.0.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

排队时，查询结果里还有 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计还要等几秒）。超过你设的等待时间也不要重新提交：任务还在，稍后用同一个任务号接着查。

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 规格速览

| 时长 | 3–30 秒，逐秒可选（默认 5 秒） |
| --- | --- |
| 分辨率 | 720P / 1080P |
| 画面比例 | 16:9 / 9:16 |
| 参考图 | 最多 10 张 · 全部作参考（人物、服装、道具、场景），不当首帧 |
| 参考视频 | 最多 5 段 · 每段 2–30 秒、高度 700–4553 像素，合计 ≤ 30 秒 · 按秒计入计费 |
| 参考音频 | 最多 3 段 · 每段 5–30 秒的清晰人声，用来定人物音色 · 不计费 |
| 声音 | 固定带声音，不能关（传 `audio: false` 会被拒绝） |
| 提示词长度 | 最多 2,500 个字符（中英文都按字符计） |
| 计费方式 | 按秒：（输出秒数 + 参考视频秒数）× 所选分辨率的每秒单价 |

## 请求参数

`POST /v1/videos/generations` 的请求体（JSON）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 id：`kling-4.0`。 |
| prompt | string | 是 | 画面、镜头、动作和声音的描述，最多 2,500 个字符。带素材时写明每个素材的用途，例如「图1的人物在图2的森林里，照参考视频里的动作挥枪，用参考音频里的嗓音说：来吧！」。 |
| duration | integer | 否 | 输出时长，3–30 之间的整数秒，默认 5；也可以写 `seconds`。 |
| resolution | string | 否 | `720P`（默认）或 `1080P`。 |
| size | string | 否 | `16:9`（默认）或 `9:16`，也可以写 `aspect_ratio`。其他比例会被拒绝（400）。 |
| images | array | 否 | 最多 10 张参考图（公网链接、`data:` URI 或 base64，单张 ≤ 16MB）；也可以写 `image`（一张）或 `reference_images`。全部作参考，不当首帧；`start_frame`、`end_frame`、`image_role=first_frame` 会被拒绝。 |
| video_references | array | 否 | 最多 5 段参考视频（mp4 / mov，每段 2–30 秒、高度 700–4553 像素、≤ 50MB，合计 ≤ 30 秒）：能直接下载的链接、base64（`data:video/mp4;base64,...`）或 Playground 上传后的链接。按秒计费，见下方「价格」。 |
| audio_reference | array | 否 | 最多 3 段参考音频（mp3 / wav / m4a，每段 5–30 秒、≤ 15MB），用来定人物的音色，必须是清晰的人声（纯音乐、音效会失败）；只收 http(s) 链接，并且要同时有参考图或参考视频。不计费。 |
| audio | boolean | 否 | 成片固定带声音，不能关闭；传 `false` 会被拒绝（400），可以不传。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址，见下文的 Webhook。 |
| n | integer | 否 | 每个任务出 1 条视频，不用传。传了大于 1 的值也只出 1 条，但提交时会按 n 条预扣，任务结束后退回多扣的部分。 |

其他字段（如 `seed`、`negative_prompt`、`fps`、`watermark`）不会转发，也不影响价格；成片一律是 MP4，通过 `url` 返回。

## 价格

按秒计费：费用 = 所选分辨率的每秒单价 ×（输出秒数 + 各参考视频的秒数）。同一个参考视频链接只算一次；参考图、参考音频不计费。提交时按这个金额预扣，成功按同样的金额结算，失败全额退回。1 积分 = $0.005。

| 分辨率 | 积分 / 秒 | 美元 / 秒 | 5 秒一条 | 输出 10 秒 + 5 秒参考视频（15 计费秒） |
| --- | --- | --- | --- | --- |
| 720P | 18 | $0.09 | $0.45 | $1.35 |
| 1080P | 25 | $0.125 | $0.625 | $1.875 |

## 参考素材

- **参考图**：全部作参考，不当首帧。在提示词里按编号写明用途，例如「图1的人物」「图2的场景」。

- **参考视频**：用来定动作和运镜，可以和参考图一起用。每段 2–30 秒，高度 700–4553 像素（例如 1280×720 横屏或 720×1280 竖屏，480P 的视频会失败），合计不超过 30 秒。提交时我们会下载并测出每段的时长和尺寸：读不出时长、太短或高度不够的，直接返回 400，不扣费。

- **参考音频**：用来定人物的音色，必须是 5–30 秒的清晰人声；纯音乐、音效或不到 5 秒的音频都会被拒绝。要说的台词写在提示词里。

- 每张图可以是公网图片链接、`data:` URI 或 base64，单张不超过 16MB，多张用数组放在 `images` 里。提交时我们先把图片转存好再排队；读不到的图片会直接返回 400，`message` 写明是第几张，这一单不计费。

- 我们转存的参考素材保留 7 天，成片保留 15 天。

**带参考图、参考视频和参考音频**

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-4.0", "prompt": "图1的侠客在图2的森林里，照参考视频里的动作挥枪，用参考音频里的嗓音喊出：来吧", "images": ["https://example.com/character.png", "https://example.com/forest.png"], "video_references": ["https://example.com/moves-1280x720.mp4"], "audio_reference": ["https://example.com/voice-8s.mp3"], "duration": 10, "resolution": "720P", "size": "16:9"}'
```

这一单输出 10 秒、参考视频 5 秒，按 15 秒计费；参考音频不计费。

## 任务状态与返回字段

`GET /v1/videos/jobs/{id}` 返回这些状态，各字段的说明见 [异步任务](https://nezhagate.com/docs/guide/async-jobs#fields)。每 5–10 秒查一次，或者用下面的 Webhook 等推送。查询不收费，同一个账号的任何 Key 都能查。

| 状态 | 含义 |
| --- | --- |
| queued | 排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 `data[0].url`，计费明细在 `usage`。 |
| failed | 失败。原因在 `error`，预扣的积分已全额退回。 |

- `processing` 有时会回到 `queued`：例如线路都在忙、成片正在重新取回，或者服务重启。某条线路没能完成任务时，网关可能把它交给下一条线重新生成；无论经过几条线，一个任务只扣一次费用。

- 同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，视频链接保留 15 天。

## 出片时间

我们的测试（720P / 1080P，3–5 秒）一般 3–5 分钟出片；排队多时会更久，最长等 120 分钟，超时全额退款。

我们的测试出片中位用时：3.3 分钟。

## 错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://nezhagate.com/docs/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | invalid_request | 参数不合法：时长、分辨率、比例或素材数量超出这个模型的范围，提示词太长，参考图或参考视频读不到，或者给固定带声音的模型传了 `audio: false` 等。`message` 写明原因。 | 按 `message` 修改后重新提交。 |
| 400 | invalid_callback_url | `callback_url` 不是公网的 http(s) 地址，或超过 2000 个字符。 | 换成能从公网访问的地址。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://nezhagate.com/docs/api) 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://nezhagate.com/status)。 |
| 503 | service_unavailable | 我们这边临时出错，例如保存参考素材失败。这一单没有创建任务，也没有扣费。 | 稍后重试。 |

### 任务失败（`status` 为 `failed`）

| code | 什么时候出现 | 怎么办 |
| --- | --- | --- |
| content_policy | 视频：提示词、参考素材，或生成的画面 / 声音没通过内容审核（声音被拦时 `param` 为 `audio`）。 Wan 标准版和 Prime：输入素材未通过审核。`error.reason` 为 `FaceDetectionSuspect`（疑似真人面部）或 `DataInspectionFailed`（输入内容审核未通过）。`error.message` 说明原因和调整建议；失败任务未计费。 | 改写提示词或更换素材后再提交；原样重交还会被拒。 |
| duration_rejected | 参考素材没有被接受：参考音频不是 5–30 秒的清晰人声，或参考视频的时长不符合要求。`param` 为 `audio` 时是音频的问题。 | 换一段 5 秒以上的人声（或去掉参考音频），参考视频剪到 2–30 秒后再提交；原样重交还会失败。 |
| render_failed | 视频：这次没有生成出成片，多为偶发。 | 原样重新提交通常就能成功。 |
| render_timeout | 视频：排队或渲染时间过长，上游放弃了这一单。 | 重新提交。 |
| result_fetch_failed | 视频已经生成，但我们反复下载或保存成片都没有成功。 | 重新提交。 |
| upstream_error | 其他失败：所有线路都试过仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等，`message` 写明具体情况。 | 通常重新提交就能成功。 |

请按 `code` 判断，不要匹配 `message` 的文字。遇到不认识的 `code`（或者没有 `code`），按 `upstream_error` 处理：重新提交通常就能成功。失败的任务一律全额退款。

## 用 Webhook 代替轮询

提交时加上 `callback_url`，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 [Webhook 文档 →](https://nezhagate.com/docs/webhooks)

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-4.0", "prompt": "一位舞者在飘落的枫叶中旋转，镜头环绕她缓缓移动", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```