kling-4.0

Kling 4.0 · API

POST https://nezhagate.com/v1/videos/generations

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

在 Playground 试用 →

快速开始

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

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

curl

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）

JSON

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

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

curl

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

成功时的返回

JSON

{
  "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：提交 → 等待 → 保存到本地）

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（预计还要等几秒）。超过你设的等待时间也不要重新提交：任务还在，稍后用同一个任务号接着查。

认证

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

规格速览

时长	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

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} 返回这些状态，各字段的说明见异步任务。每 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，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见错误码。

提交时返回的错误

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 手册里的模型 id 为准。
401	invalid_api_key	Key 不存在、已删除或已停用，或者账号已停用。	到控制台「API Keys」页面检查这把 Key。
402	insufficient_quota	余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。	如果是并发突发，稍等几秒重试；否则充值。
429	rate_limit_exceeded	超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。	等几秒再试，或在控制台调高这把 Key 的上限。
503	model_maintenance	型号维护中，暂停接单，期间不会改由其他模型作答。	维护结束后重试，进度见服务状态。
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 文档 →

curl · callback_url

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"}'

Kling 4.0 · API

快速开始

认证

规格速览

请求参数

价格

参考素材

任务状态与返回字段

出片时间

错误与退款

提交时返回的错误

任务失败（status 为 failed）

用 Webhook 代替轮询

欢迎回来

创建账户

重置密码

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