Skip to main content
Kling 系列通过 AIOAGI 视频任务接口调用。图生视频使用 POST /videos/image2video，Omni 视频使用 POST /videos/omni-video。任务创建后，你需要使用对应的 GET 接口轮询任务结果。
Kling 模型名称、价格、时长、模式、音频支持和任务状态字段可能变化。生产调用前，请在 控制台、GET /models 或 开发者指南 中核对当前可用模型。

​
接口概览

能力接口方法说明
图生视频任务/videos/image2videoPOST基于首帧图片和提示词创建视频任务。
查询图生视频/videos/image2video/{task_id}GET查询图生视频任务状态和结果。
Omni 视频任务/videos/omni-videoPOST基于图片、视频和元素参考创建多模态视频任务。
查询 Omni 视频/videos/omni-video/{task_id}GET查询 Omni 视频任务状态和结果。

​
图生视频示例

export AIO_API_KEY="sk-your-api-key"
export AIO_BASE_URL="https://api.aiearth.dev/v1"

curl "$AIO_BASE_URL/videos/image2video" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image": "https://example.com/source-image.jpg",
    "prompt": "让画面中的产品在柔和灯光下缓慢旋转，镜头轻微推进，突出金属质感和高级商业广告风格。",
    "mode": "std",
    "duration": "5",
    "sound": "on"
  }'
提交成功后，响应通常包含 task_id。请保存该 ID，用于后续查询。

​
查询图生视频结果

curl "$AIO_BASE_URL/videos/image2video/{task_id}" \
  -H "Authorization: Bearer $AIO_API_KEY"
任务状态常见值包括 submitted、processing、succeed 和 failed。不同线路也可能返回 queued、running、succeeded 或 completed。

​
Omni 视频示例

Omni 视频支持多图输入 image_list。你可以在 prompt 中使用 <<<image_1>>>、<<<image_2>>> 引用对应图片。 
curl "$AIO_BASE_URL/videos/omni-video" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-omni",
    "prompt": "让 <<<image_1>>> 中的人物走到 <<<image_2>>> 的展台前，镜头从中景缓慢推进，整体保持科技发布会风格。",
    "image_list": [
      {
        "image_url": "https://example.com/person.jpg"
      },
      {
        "image_url": "https://example.com/stage.jpg"
      }
    ],
    "duration": "5",
    "mode": "std",
    "aspect_ratio": "16:9",
    "callback_url": "",
    "external_task_id": ""
  }'

​
查询 Omni 视频结果

curl "$AIO_BASE_URL/videos/omni-video/{task_id}" \
  -H "Authorization: Bearer $AIO_API_KEY"
成功后，视频 URL 可能出现在 data.task_result.videos[]、output.video_url、output.watermark_video_url、metadata.url 或兼容字段中。请以实际响应结构为准，并在服务端记录原始响应。

​
核心参数

参数类型说明
model_namestring必填。Kling 模型 ID，例如 kling-v3 或 kling-v3-omni。
promptstring必填。描述视频动作、镜头、风格和约束。Omni 视频可引用素材占位符。
imagestring图生视频首帧图片。支持公网 URL 或 Base64。
image_listarrayOmni 视频参考图片列表。常见结构为 { "image_url": "..." }。
video_listarrayOmni 视频参考视频列表。可用于基础视频、动作或声音参考。
modestring常见值为 std 或 pro。实际支持范围以控制台和开发者指南为准。
durationstring 或 number常见值为 5 或 10 秒。实际支持范围以模型为准。
aspect_ratiostringOmni 视频画幅。常见值包括 16:9、9:16、1:1。
soundstring图生视频音效开关。常见值为 on 或 off。
negative_promptstring可选。描述不希望出现的内容。
cfg_scalenumber可选。提示词贴合程度。实际范围以当前模型为准。
callback_urlstring可选。任务完成回调地址。
external_task_idstring可选。业务侧自定义任务 ID。

​
Python 轮询示例

下面的示例展示如何轮询图生视频任务。Omni 视频只需要把查询路径改为 /videos/omni-video/{task_id}。 
import os
import time
import requests

api_key = os.environ["AIO_API_KEY"]
base_url = os.environ.get("AIO_BASE_URL", "https://api.aiearth.dev/v1")
task_id = "task_xxx"

headers = {"Authorization": f"Bearer {api_key}"}

while True:
    response = requests.get(
        f"{base_url}/videos/image2video/{task_id}",
        headers=headers,
        timeout=60,
    )
    response.raise_for_status()
    data = response.json()
    status = (
        data.get("data", {}).get("task_status")
        or data.get("output", {}).get("task_status")
        or data.get("status")
    )
    print("status:", status)

    if status in {"succeed", "succeeded", "completed"}:
        print(data)
        break
    if status in {"failed", "failure", "canceled", "cancelled"}:
        raise RuntimeError(data)

    time.sleep(5)

​
排障建议

  • 遇到 401，检查 API Key 和 Authorization 请求头。
  • 遇到 403，检查账户余额、Token 组额度和模型权限。
  • 遇到 404，核对 base URL、接口路径、模型名和 task_id。
  • 遇到 429，降低提交并发和轮询频率，并加入指数退避。
  • 任务成功但没有解析到 URL 时，保存原始响应，检查 data、output、metadata 中的视频字段。