可灵 3.0（kling-v3）文生 / 图生视频（Kling 原生协议）

ModelGo 按可灵官方 API 的路径与请求/响应格式接收请求（model_name、mode、sound、duration、aspect_ratio……），网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。轮询路径与官方一致：同一路径 + /{task_id}。

使用可灵官方 SDK / 示例代码时，把 API 域名换成 https://api.modelgo.com/kling，鉴权改为 Authorization: Bearer $MODELGO_API_KEY（无需可灵的 JWT 签名）。

1. 创建任务

文生视频

curl https://api.modelgo.com/kling/v1/videos/text2video \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "prompt": "一颗红色小球在木桌上缓缓滚动，柔和日光",
    "mode": "std",
    "duration": "5",
    "aspect_ratio": "16:9",
    "sound": "on",
    "cfg_scale": 0.5
  }'

图生视频

curl https://api.modelgo.com/kling/v1/videos/image2video \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "prompt": "小狗缓缓转头",
    "image": "https://example-cdn.com/dog.jpg",
    "mode": "pro",
    "duration": "5"
  }'

响应

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
  "data": {
    "task_id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
    "task_status": "submitted",
    "created_at": 1788773081000,
    "updated_at": 1788773081000
  }
}

data.task_id 是网关任务 ID，轮询与取内容都用它。

2. 参数说明

档位

• 只提供以上三档。 其他值会在创建时被拒（HTTP 400）。网关按各供应商可交付档位选路：请求 4k 时只会交给能出 4K 的供应商，不会静默降档；若当前没有可用的 4K 供应商，创建返回 400，不产生费用。

首帧图片的要求（image2video）

• 必须是上游服务器能直接 GET 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie；JPG / PNG，≤ 10MB，宽高 ≥ 300px，比例 1:2.5–2.5:1。
• 图片拉取失败会导致任务失败（task_status=failed），不计费。建议使用自有对象存储或 CDN 地址。

3. 轮询任务

GET https://api.modelgo.com/kling/v1/videos/text2video/{task_id}（image2video 创建的任务到 .../image2video/{task_id} 轮询）

curl https://api.modelgo.com/kling/v1/videos/text2video/gw_6dce033e-9243-4a64-9c57-73d08a8e379a \
  -H "Authorization: Bearer $MODELGO_API_KEY"

完成时：

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
  "data": {
    "task_id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
    "task_status": "succeed",
    "task_result": {
      "videos": [{"id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a", "url": "https://api.modelgo.com/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content", "duration": "6"}]
    },
    "created_at": 1788773081000,
    "updated_at": 1788773250000
  }
}

• task_status：submitted → processing → succeed / failed。失败时 task_status_msg 给出原因，任务不计费。
• 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。
• videos[].url 指向网关内容接口，需带 API Key 下载；duration 为实际交付秒数。

4. 下载视频

GET https://api.modelgo.com/v1/videos/{task_id}/content

curl https://api.modelgo.com/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content \
  -H "Authorization: Bearer $MODELGO_API_KEY" -o kling.mp4

返回 video/mp4 字节流，支持 Range。只有任务所属 API Key（或同租户控制台登录态）能访问；未完成返回 409，过期或不存在返回 404。

5. 完整示例（Python）

import os, time, requests

BASE = "https://api.modelgo.com/kling/v1/videos"
H = {"Authorization": f"Bearer {os.environ['MODELGO_API_KEY']}"}

def generate(kind: str, body: dict, out: str, timeout: int = 600) -> None:
    body.setdefault("model_name", "kling-v3")
    r = requests.post(f"{BASE}/{kind}", json=body, headers=H, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["task_id"]
    deadline = time.time() + timeout
    while True:
        if time.time() > deadline:
            raise TimeoutError(task_id)
        data = requests.get(f"{BASE}/{kind}/{task_id}", headers=H, timeout=30).json()["data"]
        if data["task_status"] == "succeed":
            break
        if data["task_status"] == "failed":
            raise RuntimeError(data.get("task_status_msg", "generation failed"))
        time.sleep(8)
    url = data["task_result"]["videos"][0]["url"]
    with requests.get(url, headers=H, stream=True, timeout=120) as c:
        c.raise_for_status()
        with open(out, "wb") as f:
            for chunk in c.iter_content(1 << 20):
                f.write(chunk)

generate("text2video", {"prompt": "一颗红色小球在木桌上缓缓滚动", "mode": "std", "duration": "5", "sound": "on"}, "t2v.mp4")
generate("image2video", {"prompt": "小狗缓缓转头", "image": "https://example-cdn.com/dog.jpg", "mode": "pro", "duration": "5"}, "i2v.mp4")

6. 计费口径

• 按视频秒数 × 单价计费，单价由三个维度决定：输入方式（文生 / 图生）、档位（std 720P / pro 1080P / 4k）、是否生成音频（sound）。
• 创建时按请求的 duration 预授权冻结，任务完成后按实际交付秒数结算；部分通道多交付约 1 秒（请求 5 秒交付 6 秒），以 videos[].duration 为准。
• 未传时长按缺省值预授权（万相 / 可灵 5 秒，Veo 8 秒），缺省值同时发给供应商；结算取供应商回报的实际交付秒数，四舍五入到整秒（如 5.041 → 5，5.5 → 6），可能与请求时长相差 ±1 秒。
• 创建被拒（400）或生成失败（failed）不计费，预授权自动释放。
• 各档单价以控制台「模型列表」中的价格为准。

常见错误