可灵 3.0

ModelGo 按可灵官方 3.0 API 的路径与请求/响应格式接收请求（settings、options、contents[]……），网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。

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

1. 创建任务

文生视频

curl https://api.modelgo.ai/kling/text-to-video/kling-3.0 \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一颗红色小球在木桌上缓缓滚动，柔和日光",
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "duration": 5,
      "audio": "native"
    }
  }'

图生视频

curl https://api.modelgo.ai/kling/image-to-video/kling-3.0 \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"type": "prompt", "text": "小狗缓缓转头"},
      {"type": "first_frame", "url": "https://example-cdn.com/dog.jpg"}
    ],
    "settings": {"resolution": "1080p", "duration": 5}
  }'

响应

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
  "data": {
    "id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
    "status": "submitted",
    "create_time": 1788773081000,
    "update_time": 1788773081000
  }
}

data.id 是网关任务 ID，轮询与取内容都用它。时间戳为毫秒。

2. 参数说明

请求体

contents[]（image-to-video）

settings

options

• 上表之外的字段会在创建时被拒绝（HTTP 400，消息指出字段名），不会被忽略。
• multi_shot: true、element、watermark_info.enabled: true 只会路由到能原样转发它们的供应商通道；当前没有这样的通道可用时返回 400（error_class=provider_unsupported），不会静默丢弃后按普通视频计费。这些字段本身不改变单价。

分镜

settings.multi_shot 为 true 时，分镜写在 prompt 里：

• 自定义分镜：按 镜头 n, 秒数, 描述; 逐条书写，例如 镜头 1, 3, 一只猫在窗边眨眼; 镜头 2, 3, 猫伸了个懒腰;。镜头从 1 起顺序编号，最多 6 个，每个镜头描述 ≤ 512 字符，各镜头秒数之和必须等于 settings.duration（缺省 5），否则创建返回 400。
• 自动分镜：prompt 不使用上述写法时，由模型按提示词自动拆分镜头。

档位

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

首帧图片的要求（image-to-video）

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

3. 轮询任务

GET https://api.modelgo.ai/kling/tasks?task_ids={id}

curl "https://api.modelgo.ai/kling/tasks?task_ids=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": [
    {
      "id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
      "status": "succeeded",
      "create_time": 1788773081000,
      "update_time": 1788773250000,
      "outputs": [
        {
          "type": "video",
          "id": "gw_6dce033e-9243-4a64-9c57-73d08a8e379a",
          "url": "https://api.modelgo.ai/v1/videos/gw_6dce033e-9243-4a64-9c57-73d08a8e379a/content",
          "duration": "6"
        }
      ]
    }
  ]
}

• status：submitted → processing → succeeded / failed。失败时 message 给出原因，任务不计费。
• 每次请求只查询一个任务：task_ids 传单个 ID（逗号分隔的多个 ID 与 external_task_ids 会返回 400）。
• 生成耗时通常 1–3 分钟，请按 5–10 秒间隔轮询并带退避。
• outputs[].url 指向网关内容接口，需带 API Key 下载；duration 为实际交付秒数。

4. 下载视频

GET https://api.modelgo.ai/v1/videos/{id}/content

curl https://api.modelgo.ai/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.ai/kling"
H = {"Authorization": f"Bearer {os.environ['MODELGO_API_KEY']}"}

def generate(path: str, body: dict, out: str, timeout: int = 600) -> None:
    r = requests.post(f"{BASE}/{path}/kling-3.0", json=body, headers=H, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["id"]
    deadline = time.time() + timeout
    while True:
        if time.time() > deadline:
            raise TimeoutError(task_id)
        task = requests.get(f"{BASE}/tasks", params={"task_ids": task_id}, headers=H, timeout=30).json()["data"][0]
        if task["status"] == "succeeded":
            break
        if task["status"] == "failed":
            raise RuntimeError(task.get("message", "generation failed"))
        time.sleep(8)
    url = task["outputs"][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("text-to-video", {"prompt": "一颗红色小球在木桌上缓缓滚动", "settings": {"resolution": "720p", "duration": 5, "audio": "native"}}, "t2v.mp4")
generate("image-to-video", {"contents": [{"type": "prompt", "text": "小狗缓缓转头"}, {"type": "first_frame", "url": "https://example-cdn.com/dog.jpg"}], "settings": {"resolution": "1080p", "duration": 5}}, "i2v.mp4")

6. 计费口径

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

错误响应

失败的请求保持对应的 HTTP 状态码，响应体与官方一致：{"code": 1201, "message": "…", "request_id": "…"}。code 取官方错误码表的业务码，按 HTTP 状态归类：400→1201、401→1000、403→1103、404→1203、405→1202、429→1302、500→5000、503→5001、504→5002；message 指出具体原因。任务本身生成失败不是请求错误：仍返回 code=0，任务 status=failed，原因在 message。

常见错误