可灵 4.0 API（kling-v4）接入：参数、价格与代码

先说答案：可灵 4.0 已在 HopBase 上线，模型 ID 是 kling-v4。它可以用一段文字提示词，或者一张首帧图片，生成 3 到 30 秒的视频，分辨率 720p 或 1080p，画幅 16:9、9:16、1:1、21:9 可选。成片总是带音轨：传 audio: false 既去不掉声音，也不会更便宜。调用方式是异步任务：先 POST https://api.hop-base.com/v1/video/generate 提交，拿到以 kt 开头的任务 ID，再轮询 GET /v1/video/tasks/{task_id}，直到状态变成 completed 或 failed，一般几分钟出片。官方牌价 720p 每秒 $0.1471、1080p 每秒 $0.2206，按成片秒数计费，失败不扣费。参考图、参考视频和 2K/4K 目前 kling-v4 还不支持。结果链接 24 小时内有效；用的是同一把 HopBase Key 和美元余额，不需要单独开可灵账号。

可灵 4.0 新在哪，什么时候继续用 3.0

可灵 4.0 于 2026-10-29 在 HopBase 上线。和同一把 Key 能调的可灵 3.0 系列相比，它单条最长可到 30 秒（3.0 是 15 秒），新增 21:9 宽银幕画幅，而且每条成片都有声音。输入端反而更简单：只有文字提示词，外加可选的一张首帧图。

	kling-v4	kling-v3	kling-v3-omni
时长	3–30 秒	3–15 秒	3–15 秒
分辨率	720p / 1080p	720p / 1080p / 2K / 4K	720p / 1080p / 2K / 4K
画幅	16:9 / 9:16 / 1:1 / 21:9	16:9 / 9:16 / 1:1	16:9 / 9:16 / 1:1
声音	总是有声	有声 / 无声可选	有声 / 无声可选
图片输入	仅首帧	首尾帧，最多 6 张参考图	首尾帧、参考图
参考视频	不支持	不支持	支持（feature）
主体 / 多镜头 shots	不支持	支持	支持
官方牌价（1080p 有声）	$0.2206 / 秒	$0.1765 / 秒	$0.1471 / 秒

需要单条超过 15 秒、要 21:9 画幅，或者希望每条成片都带声音、不想管 audio 开关时，选 kling-v4。需要参考图、参考视频、用自定义主体保持角色一致、做多镜头分镜，或者要 2K/4K 时，继续用 kling-v3 / kling-v3-omni，shots 与主体的用法见可灵 3.0 多镜头分镜指南。画质高低我们不在这里下结论，建议用同一段提示词在两个模型上各跑一次自己对比。

价格：按成片秒数计费

kling-v4 按成片时长计费，单价取决于你请求的分辨率，有声无声同价。以下是 kling-v4 模型卡上的官方牌价：

分辨率	官方牌价	5 秒	10 秒	30 秒
720p	$0.1471 / 秒	≈ $0.74	≈ $1.47	≈ $4.41
1080p	$0.2206 / 秒	≈ $1.10	≈ $2.21	≈ $6.62

你自己的实际单价取决于 Key 绑定的分组，以登录后模型目录显示为准。只有成功完成的任务才计费，失败任务一律不扣。任务完成后，响应里的 usage.cost_usd 就是这条任务实际从余额扣掉的金额。可灵其他型号的价格见价格页。

第一步（a）：文生视频

可灵所有模型共用同一个接口，用 HopBase Key 作 Bearer 鉴权：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "雨夜霓虹街道，镜头缓慢推轨前进，柏油路面倒映灯光，远处车流声",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "21:9"
  }'

逐个字段说明：

• model：kling-v4。
• prompt：没有图片时必填，最长 2,500 个字符。
• duration：整数秒，3 到 30。不传时网关按 5 秒。
• resolution：720p 或 1080p，同时决定价格档。不传时网关按 720p。
• aspect_ratio：16:9、9:16、1:1 或 21:9。不传时网关不会代填，文生视频建议显式写上。
• audio：可以不传，成片总是有声，价格也不变。

提交成功返回 202，任务 ID 在顶层 id：

{
  "id": "kt57xYOUR_TASK_ID",
  "object": "video.generation.task",
  "model": "kling-v4",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "1080p_..."
}

第一步（b）：首帧图生视频

想让一张静态图动起来，把它放进 images[]，并标 usage: "first_frame"：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "镜头缓缓推近，咖啡杯上升起热气",
    "duration": 8,
    "resolution": "720p",
    "images": [
      { "url": "https://cdn.example.com/coffee.png", "usage": "first_frame" }
    ]
  }'

• 成片画幅跟随输入图，aspect_ratio 不生效。想要竖屏成片，先把图裁成 9:16。
• 每个图片项必须且只能有 url 或 file_id 其中之一。url 必须是公网可访问的 http(s) 绝对地址；相对路径、file://、内网或回环 IP、带账号密码的 URL 在提交时就会被拒。
• 每张图都必须写 usage。kling-v4 只接受首帧，传 usage: "reference" 会返回 400：model kling-v4 does not support reference-based generation。

第二步：轮询到任务结束

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

status 从 queued 到 processing，最终停在 completed 或 failed。只有这两个是终态，其他值一律当作还在跑。完成时长这样：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "1080p_...", "billed_seconds": 10, "cost": ..., "cost_usd": 2.206, "currency": "CNY" }
}

outputs 里是 api.hop-base.com 上的签名链接，从任务完成起 24 小时有效；再次查询返回同一个链接、不会续期，过期返回 410，所以拿到后请立刻转存到自己的存储。usage.cost_usd 是从美元余额实际扣掉的金额，cost 是同一笔费用的人民币表示。

任务失败时查询仍返回 HTTP 200，status 为 failed，并带稳定的 error.code：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "failed",
  "error": { "code": "input_sensitive", "message": "..." }
}

完整 Python 示例

下面的脚本提交一条文生视频任务，每 10 秒轮询一次，完成后把 MP4 下载到本地：

import time
import requests

API = "https://api.hop-base.com/v1"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

resp = requests.post(f"{API}/video/generate", headers=HEADERS, json={
    "model": "kling-v4",
    "prompt": "阳光下的森林小溪，一只纸船顺流漂下，鸟鸣和流水声",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
})
resp.raise_for_status()
task_id = resp.json()["id"]
print("submitted", task_id)

while True:
    task = requests.get(f"{API}/video/tasks/{task_id}", headers=HEADERS).json()
    status = task["status"]
    if status == "completed":
        url = task["outputs"][0]
        with requests.get(url, stream=True) as r:
            r.raise_for_status()
            with open(f"{task_id}.mp4", "wb") as f:
                for chunk in r.iter_content(chunk_size=1 << 20):
                    f.write(chunk)
        print("saved", f"{task_id}.mp4", "charged $", task["usage"]["cost_usd"])
        break
    if status == "failed":
        err = task.get("error", {})
        raise RuntimeError(f'{err.get("code")}: {err.get("message")}')
    time.sleep(10)

可灵的请求里没有回调（webhook）字段，跟踪任务只能靠轮询。创建后 2 小时仍未完成的任务会被标记为失败（error.code 为 timeout），不计费；任务不能取消。如果你同时在用多家视频模型，一个 API 接入 Seedance、可灵、海螺和万相里有一段三家通用的轮询代码。

常见报错

请求体按严格模式解析，提交阶段的错误会立刻返回，不建任务、不扣费：

你发了什么	error.message
duration 超出 3–30	model kling-v4 supports 3 to 30 seconds, got 40
图片带 usage: "reference"	model kling-v4 does not support reference-based generation
图片没写 usage	images[0].usage is required for standard Kling video requests
resolution 传 "2k" 或 "4k"	model "kling-v4" does not support billing bucket "..." for this request
带了 OpenAI 习惯的字段，比如 size	request body does not match the JSON contract: json: unknown field "size"
既没有提示词也没有图片	prompt and input media cannot both be empty

返回 402、code 为 insufficient_balance，表示余额减去在途任务和本次任务的预估费用后不够；任务结束后预占会自动释放。

素材本身由可灵在任务运行时检查，不在提交时检查。图片下载不了、格式或尺寸不合规时，任务会先被接受，几分钟后以 reference_input_invalid 失败；提示词或图片被内容审核拦截时以 input_sensitive 失败。这些失败都不计费。完整报错对照见可灵视频 API 文档。

常见问题

可灵 4.0 的模型 ID 是什么？

kling-v4。发付费任务前，先用你的 Key 调 GET /v1/models，确认它在 Key 绑定的分组里。

可灵 4.0 一条视频最长多少秒？

每个任务 3 到 30 秒，整数秒。不传 duration 时默认 5 秒。

可灵 4.0 支持 2K 或 4K 吗？

暂不支持，kling-v4 只有 720p 和 1080p。需要 2K/4K 请用 kling-v3 或 kling-v3-omni。

能关掉声音吗？

不能。即使传 audio: false，成片也带音轨，价格也一样。需要静音文件的话，下载后自己去掉音轨。

可灵 4.0 支持参考图或参考视频吗？

不支持。它只接受文字提示词和可选的一张首帧图。需要参考图、参考视频、自定义主体或多镜头分镜，请用 kling-v3-omni 或 kling-v3。

图生视频时 aspect_ratio 为什么不生效？

传了首帧图时，成片画幅跟随输入图，aspect_ratio 会被忽略。提交前先把图裁成想要的比例。

生成要多久？

一般几分钟。建议每 5 到 10 秒轮询一次。创建 2 小时后仍未完成的任务以 timeout 失败，不扣费。

一条 10 秒 1080p 的可灵 4.0 视频多少钱？

按官方牌价，10 × $0.2206 ≈ $2.21。每条任务的实际扣费在 usage.cost_usd 里返回，也会出现在使用记录中。

怎么开通？

在 HopBase 控制台创建 API Key，绑定包含可灵的分组，再用 GET /v1/models 确认能看到 kling-v4。同一把 Key 只要分组包含，也能调可灵动作控制、可灵数字人，以及视频总览里的其他视频模型。