Kling 3.0 异步任务与示例

创建 Kling 任务使用模型 API Token；查询任务使用资源 API Key。请求体只接受 JSON，参考图只接受绝对 HTTP/HTTPS URL。

视频提示词最多 1200 个 Unicode 字符。output.generate_audio 控制成片音轨，省略时默认 true。

环境变量

export SUPERTOKEN_BASE_URL="https://api.supertoken.cc"
export SUPERTOKEN_KEY="YOUR_MODEL_API_TOKEN"
export RESOURCE_API_KEY="YOUR_RESOURCE_API_KEY"

Kling 3.0 纯文本生成

不传 input.image 和 input.reference_images 时，Kling 3.0 根据提示词生成视频：

export VIDEO_MODEL="adobe-kling-3.0-720p"

curl -i -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kling-text-20260802-001" \
  -d '{
    "model": "'"$VIDEO_MODEL"'",
    "operation": "generation",
    "input": {
      "prompt": "一辆红色跑车沿海岸公路缓慢行驶，日出，电影感运镜"
    },
    "output": {
      "duration": 3,
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

Kling 3.0 单帧生成

需要约束视频起始画面时，可以提供一张首帧图。下面创建一个 3 秒的 720p 横屏任务：

export VIDEO_MODEL="adobe-kling-3.0-720p"

curl -i -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kling-single-frame-20260730-001" \
  -d '{
    "model": "'"$VIDEO_MODEL"'",
    "operation": "generation",
    "input": {
      "prompt": "保持人物外观，一阵海风吹动头发，镜头缓慢靠近",
      "reference_mode": "frame",
      "image": {
        "url": "https://media.example.com/kling/portrait-start.jpg",
        "name": "start"
      }
    },
    "output": {
      "duration": 3,
      "aspect_ratio": "16:9"
    },
    "client_reference_id": "order-kling-001",
    "metadata": {
      "scene": "coast"
    }
  }'

Kling 3.0 首尾帧

input.image 是首帧，input.reference_images[0] 是尾帧：

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kling-two-frames-20260730-001" \
  -d '{
    "model": "adobe-kling-3.0-1080p",
    "operation": "generation",
    "input": {
      "prompt": "从日景自然过渡到夜景，建筑结构保持稳定",
      "reference_mode": "frame",
      "image": {
        "url": "https://media.example.com/kling/day.jpg",
        "name": "start"
      },
      "reference_images": [
        {
          "url": "https://media.example.com/kling/night.jpg",
          "name": "end"
        }
      ]
    },
    "output": {
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

frame 最多两张图，第三张会被拒绝。

Kling 3.0 Omni 三图参考

Omni 使用 images 时，最多传三张普通参考图。它们不会被解释成首帧或尾帧：

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks" \
  -H "Authorization: Bearer $SUPERTOKEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kling-omni-images-20260730-001" \
  -d '{
    "model": "adobe-kling-3.0-omni-720p",
    "operation": "generation",
    "input": {
      "prompt": "使用 @character 的人物、@wardrobe 的服装和 @location 的场景，人物走向镜头",
      "reference_mode": "images",
      "reference_images": [
        {
          "url": "https://media.example.com/kling/character.jpg",
          "name": "character"
        },
        {
          "url": "https://media.example.com/kling/wardrobe.jpg",
          "name": "wardrobe"
        },
        {
          "url": "https://media.example.com/kling/location.jpg",
          "name": "location"
        }
      ]
    },
    "output": {
      "duration": 5,
      "aspect_ratio": "9:16",
      "generate_audio": false
    }
  }'

Kling 3.0 非 Omni 模型不支持 images。所有 Kling 模型都不接受 reference_videos、reference_audios 或 media 模式。

创建响应

任务受理后返回 202 Accepted：

Location: /v1/video/tasks/task_example123
Retry-After: 2

{
  "id": "task_example123",
  "object": "video.task",
  "model": "adobe-kling-3.0-720p",
  "operation": "generation",
  "status": "queued",
  "progress": 0,
  "result": null,
  "error": null,
  "client_reference_id": "order-kling-001",
  "metadata": {
    "scene": "coast"
  },
  "created_at": 1785373200,
  "started_at": null,
  "completed_at": null,
  "updated_at": 1785373200
}

相同账号使用同一个 Idempotency-Key 和完全相同的请求时会返回原任务。相同 Key 配合不同请求会返回 409 idempotency_key_conflict。

查询与轮询

export TASK_ID="task_example123"

curl -sS "$SUPERTOKEN_BASE_URL/v1/video/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" |
jq '{id, status, progress, result, error}'

状态	含义
queued	已创建，等待执行
in_progress	上游正在生成
succeeded	已完成，从 result.videos[] 读取结果
failed	已失败，读取 error.code、message 和 retryable

建议至少间隔 2 秒轮询，或按创建响应中的 Retry-After 执行。

成功结果与下载

成功任务会在 result.videos[] 中返回结果 URL：

{
  "id": "task_example123",
  "object": "video.task",
  "model": "adobe-kling-3.0-720p",
  "operation": "generation",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "videos": [
      {
        "asset_id": "asset_example123",
        "index": 0,
        "url": "https://media.example.com/results/video.mp4?token=...",
        "mime_type": "video/mp4",
        "filename": "task_example123.mp4",
        "duration_ms": 3000,
        "temporary": true,
        "url_auth": "none"
      }
    ]
  },
  "error": null,
  "created_at": 1785373200,
  "started_at": 1785373202,
  "completed_at": 1785373268,
  "updated_at": 1785373268
}

url_auth: "none" 表示浏览器或下载程序直接访问 URL，不要附加 SuperToken Key：

VIDEO_URL=$(curl -sS \
  "$SUPERTOKEN_BASE_URL/v1/video/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RESOURCE_API_KEY" |
  jq -r '.result.videos[0].url')

curl -L "$VIDEO_URL" --output kling-result.mp4

临时结果地址

temporary: true 表示 URL 可能过期。SuperToken 不刷新、不归档这条 URL，也不保证有效期。需要长期保存时请在 URL 有效期内转存；不要把完整签名参数写入普通日志。

如果 url_auth 是 resource_api_key，访问 URL 时需要携带 Authorization: Bearer $RESOURCE_API_KEY。客户端应始终根据响应字段选择下载方式。

当前 duration_ms 回显已验证的请求时长，不表示 SuperToken 下载结果媒体重新探测了真实时长，也不会触发二次计费。

Python 完整轮询示例

下面的程序创建一条 Kling 3.0 单帧任务并轮询到终态，只使用 Python 标准库：

import json
import os
import time
import urllib.request
import uuid

base_url = os.environ.get(
    "SUPERTOKEN_BASE_URL", "https://api.supertoken.cc"
).rstrip("/")
model_key = os.environ["SUPERTOKEN_KEY"]
resource_key = os.environ["RESOURCE_API_KEY"]
reference_url = os.environ["REFERENCE_IMAGE_URL"]


def request_json(method, path, token, body=None, headers=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    request = urllib.request.Request(
        f"{base_url}{path}",
        data=data,
        method=method,
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            **(headers or {}),
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers


request_id = f"kling-{uuid.uuid4()}"
task, headers = request_json(
    "POST",
    "/v1/video/tasks",
    model_key,
    {
        "model": "adobe-kling-3.0-720p",
        "operation": "generation",
        "input": {
            "prompt": "人物转身看向镜头，轻微风吹动头发",
            "reference_mode": "frame",
            "image": {"url": reference_url, "name": "start"},
        },
        "output": {"duration": 3, "aspect_ratio": "16:9"},
        "client_reference_id": request_id,
    },
    {"Idempotency-Key": request_id},
)

poll_seconds = max(int(headers.get("Retry-After", "2")), 2)
print("created:", task["id"])

while task["status"] not in {"succeeded", "failed"}:
    time.sleep(poll_seconds)
    task, _ = request_json(
        "GET", f"/v1/video/tasks/{task['id']}", resource_key
    )
    print(task["status"], task["progress"])

if task["status"] == "failed":
    raise RuntimeError(task["error"])

for video in task["result"]["videos"]:
    print(video["asset_id"], video["url_auth"], video["url"])

运行前设置参考图 URL：

export REFERENCE_IMAGE_URL="https://media.example.com/kling/start.jpg"
python3 kling_async.py

Webhook

不希望持续轮询时，配置视频 Webhook。Webhook 的 data.object 与任务查询响应一致；收到事件后仍可使用资源 API Key查询一次任务确认最终状态。

下一步

• Kling 参数与错误
• 视频 Webhook
• Kling 3.0 概览