API 协议

Kling 4.0:参数、场景与调用指南

预览指南

粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。

预览指南

Kling 4.0:参数、场景与调用指南

直接答案contents 是数组,文本项为 type=prompt/text;settings 统一设置时长、清晰度和比例。也可使用简单 prompt/seconds/size。

更新 · 审核信息

模型定位与适用场景

标准版支持从文本、帧图片、参考图或视频构建镜头;自定义音色先创建,再以 voice_id 引用。不要把 Flash 与标准版的素材协议混用。

本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。

型号与入口

kling-4.0

POST /v1/videos

参考素材格式

素材字段传输格式文件准备与限制
图片 / 首尾帧contents[].url (first_frame / middle_frame / last_frame / refer_image)HTTP(S) 图片直链;PNG/JPEG 裸 Base64 或 data:image/png;base64,... / data:image/jpeg;base64,...。内联图片解码后最多 30 MiB;推荐 PNG/JPEG。JSON 请求不能填写电脑路径;多图片引用需唯一 id。
参考 / 编辑视频contents[].url (feature_video / base_video)仅 HTTP(S) 视频直链;不支持裸 Base64 或视频 data URI。推荐 MP4(H.264);feature_video 用于参考,base_video 用于编辑。最多 5 段视频,base_video 最多 1 段。
参考音频POST /v1/general/custom-voices: voice_url 或 file先创建音色:JSON voice_url 为 HTTP(S) MP3/WAV/MP4/MOV 直链;本地文件用 multipart 的 file。不能把音频 URL/Base64 放入 voice_id。本地上传为 5–30 秒、≤15 MiB 的 PCM WAV。当前两站创建入口实测 404;此流程需接口上线,未完成音色创建验收。
音色 IDcontents[].voice_id + id仅本站音色创建成功返回的 voice_id;提示词用 @id 引用。task_id 是查询创建任务用的 ID,不是 voice_id。标准版最多 3 个音色;不直接接收参考音频。

参数与组合限制

  • contents 是数组,文本项为 type=prompt/text;settings 统一设置时长、清晰度和比例。也可使用简单 prompt/seconds/size。
  • first_frame/middle_frame/last_frame 控制帧;refer_image 是参考图,feature_video 是参考视频,base_video 是待编辑视频。
  • 图片最多 10 张、视频最多 5 段、base_video 最多 1 段、音色最多 3 个,全部素材合计最多 15。多个参考图或中间帧需唯一 id。
  • voice_id 不是音频 URL。POST /v1/general/custom-voices 创建音色,GET 同路径/{task_id} 查询;成功后用 voice_id 和本次引用名 id。该新接口需本站已启用。
  • voice 的 id=voice_1 对应提示词 @voice_1。当前不提供音色列表和删除;不要尝试 refer_audio/audio/reference_audio 内容类型。
  • input 包裹与顶层 contents/settings 不混用;顶层 prompt 与 contents 二选一。参考媒体是否满足时长、格式和内容要求还需生成终态确认。
  • 2026-11-15 业务站实测:3 秒首尾帧、base_video 编辑均出片并下载解码,编辑结果已观察到背景颜色变化。此结论不涵盖中间帧、feature_video、音色或其他站点的接入模式。主站和业务站 POST /v1/general/custom-voices 均返回 404,本地 WAV 创建音色、获得 voice_id 及带音色生成尚未完成线上验收。
字段类型用法与限制
Authorizationheader string必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。
modelstring必填 kling-4.0;不将标准版参数套到 Flash 或旧版。
promptstring本站纯文本快捷方式,与 contents 二选一,转换为 type=prompt 的内容项。
contentsobject[]必须含 prompt 项。文本及素材数组;素材总数最多 15,图片 ≤10、视频 ≤5、主体 ≤7、音色 ≤3;视频主体也占用视频配额。
contents[].typestring每项必填:prompt/first_frame/middle_frame/last_frame/refer_image/feature_video/base_video/element/voice。middle_frame 和 base_video 依赖支持该模式的本站渠道,不是所有渠道都接收。
contents[].textstringprompt 项必填;本站校验英文最多 26000 字符、非英文最多 11000 字符,混合按比例计;引用素材用 @id。
contents[].urlstring帧、图片、视频项使用;图片支持 HTTP(S) 或对应渠道支持的图片 Base64,视频使用 HTTP(S) URL。voice/element 不用媒体 URL 代替资源 ID。 官方图片 JPG/JPEG/PNG、≤30 MB、边长 ≥300 px、比例 0.4–2.5。 官方视频 MP4/MOV,≤300 MB,单段及总长 3–30 秒,24–60 fps;总长包括视频主体。
contents[].idstring提示词中的素材引用名,非空且在请求内唯一;多个中间帧、参考图需分别命名,voice/element 必填。
contents[].element_idstringelement 必填。使用本人可访问的本站主体 ID;创建并查询成功后使用,不是本次引用名 id。
contents[].voice_idstringvoice 必填。使用创建成功的本站音色 ID;不能填音频 URL,音色创建流程及已知可用性限制见音色指南。
settings.durationinteger3–30 秒;本站省略时显式发送 10,不依赖提示词推断时长。
settings.audiostring可选 native(默认,同步生成声音)/original(保留输入视频声音)。original 必须包含 base_video 或 feature_video,且不能同时传 voice;优先使用 base_video,否则用第一个 feature_video。已支持参数校验和转发,音轨效果仍需真实生成验收。
settings.resolutionstring720p/1080p;本站默认 1080p。不要把创作端 4K 宣传当作当前本站 API 枚举。
settings.aspect_ratiostring支持 adaptive/16:9/9:16/1:1/21:9/4:3/3:4;adaptive 用于支持它的参考模式。与 size 同时指定时不能冲突。
options.watermark_info.enabledboolean可选水印开关;本站兼容顶层 watermark,不要传冲突值,显式 false 保留。 官方默认 false,不支持自定义水印。
options.external_task_idstring可选业务关联标识,不提供创建请求幂等保证。 官方要求在同账号内唯一,不替换服务生成的任务 ID。
options.callback_urlstring可选 HTTP(S) 回调地址。支持的渠道可能转为顶层 callback_url;保持主动查询,不假定回调返回本站 ID。
seconds / size / watermarksite aliases分别映射 duration、resolution+aspect_ratio、水印;和嵌套设置冲突会报错,推荐嵌套字段。

场景与代码示例

文生视频

适用型号:kling-4.0

POST /v1/videos

{
  "model": "kling-4.0",
  "prompt": "一位旅行者在海边散步,镜头平稳跟拍。",
  "seconds": "8",
  "size": "1280x720",
  "watermark": false
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "一位旅行者在海边散步,镜头平稳跟拍。",
  "seconds": "8",
  "size": "1280x720",
  "watermark": false
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"kling-4.0\",\"prompt\":\"一位旅行者在海边散步,镜头平稳跟拍。\",\"seconds\":\"8\",\"size\":\"1280x720\",\"watermark\":false}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "kling-4.0",
  "prompt": "一位旅行者在海边散步,镜头平稳跟拍。",
  "seconds": "8",
  "size": "1280x720",
  "watermark": false
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

首尾帧与中间帧

适用型号:kling-4.0

POST /v1/videos

{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "从首帧平稳过渡到 @middle 再到尾帧。"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/subject.png"
    },
    {
      "type": "middle_frame",
      "url": "https://example.com/middle.png",
      "id": "middle"
    },
    {
      "type": "last_frame",
      "url": "https://example.com/end.png"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "从首帧平稳过渡到 @middle 再到尾帧。"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/subject.png"
    },
    {
      "type": "middle_frame",
      "url": "https://example.com/middle.png",
      "id": "middle"
    },
    {
      "type": "last_frame",
      "url": "https://example.com/end.png"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"kling-4.0\",\"contents\":[{\"type\":\"prompt\",\"text\":\"从首帧平稳过渡到 @middle 再到尾帧。\"},{\"type\":\"first_frame\",\"url\":\"https://example.com/subject.png\"},{\"type\":\"middle_frame\",\"url\":\"https://example.com/middle.png\",\"id\":\"middle\"},{\"type\":\"last_frame\",\"url\":\"https://example.com/end.png\"}],\"settings\":{\"duration\":8,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "从首帧平稳过渡到 @middle 再到尾帧。"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/subject.png"
    },
    {
      "type": "middle_frame",
      "url": "https://example.com/middle.png",
      "id": "middle"
    },
    {
      "type": "last_frame",
      "url": "https://example.com/end.png"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

多参考图

适用型号:kling-4.0

POST /v1/videos

{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "@person 站在 @scene 中,光照自然。"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/subject.png",
      "id": "person"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/end.png",
      "id": "scene"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "@person 站在 @scene 中,光照自然。"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/subject.png",
      "id": "person"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/end.png",
      "id": "scene"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"kling-4.0\",\"contents\":[{\"type\":\"prompt\",\"text\":\"@person 站在 @scene 中,光照自然。\"},{\"type\":\"refer_image\",\"url\":\"https://example.com/subject.png\",\"id\":\"person\"},{\"type\":\"refer_image\",\"url\":\"https://example.com/end.png\",\"id\":\"scene\"}],\"settings\":{\"duration\":8,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "@person 站在 @scene 中,光照自然。"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/subject.png",
      "id": "person"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/end.png",
      "id": "scene"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

视频动作参考

适用型号:kling-4.0

POST /v1/videos

{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "参考 @motion 的动作和运镜。"
    },
    {
      "type": "feature_video",
      "url": "https://example.com/action.mp4",
      "id": "motion"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "参考 @motion 的动作和运镜。"
    },
    {
      "type": "feature_video",
      "url": "https://example.com/action.mp4",
      "id": "motion"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"kling-4.0\",\"contents\":[{\"type\":\"prompt\",\"text\":\"参考 @motion 的动作和运镜。\"},{\"type\":\"feature_video\",\"url\":\"https://example.com/action.mp4\",\"id\":\"motion\"}],\"settings\":{\"duration\":8,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "参考 @motion 的动作和运镜。"
    },
    {
      "type": "feature_video",
      "url": "https://example.com/action.mp4",
      "id": "motion"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

视频编辑

适用型号:kling-4.0

POST /v1/videos

{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "将 @source 的背景改成海滩,保持人物动作。"
    },
    {
      "type": "base_video",
      "url": "https://example.com/action.mp4",
      "id": "source"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "将 @source 的背景改成海滩,保持人物动作。"
    },
    {
      "type": "base_video",
      "url": "https://example.com/action.mp4",
      "id": "source"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"kling-4.0\",\"contents\":[{\"type\":\"prompt\",\"text\":\"将 @source 的背景改成海滩,保持人物动作。\"},{\"type\":\"base_video\",\"url\":\"https://example.com/action.mp4\",\"id\":\"source\"}],\"settings\":{\"duration\":8,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\"}}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "将 @source 的背景改成海滩,保持人物动作。"
    },
    {
      "type": "base_video",
      "url": "https://example.com/action.mp4",
      "id": "source"
    }
  ],
  "settings": {
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

自定义音色

适用型号:kling-4.0

POST /v1/videos

当前两站音色创建入口实测 404,尚不能获得本站 voice_id。以下为接口启用后的请求契约,不代表功能已上线;占位 ID 不可提交。

{
  "model": "kling-4.0",
  "contents": [
    {
      "type": "prompt",
      "text": "人物用 @voice_1 的声音说:欢迎。"
    },
    {
      "type": "voice",
      "voice_id": "voice_REPLACE_WITH_RESULT",
      "id": "voice_1"
    }
  ],
  "settings": {
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

本地 WAV 创建音色

需本站已启用音色创建能力。使用 5–30 秒、最大 15 MiB 的 PCM WAV;voice_name 为 1–20 字符。multipart 中 file 与 JSON 中 voice_url 是两种方式,不要混传;让 HTTP 库自动生成 multipart boundary。查询到 data.task_status=succeed 后读取 data.task_result.voices[0].voice_id,再放入上面的 voice 项。创建失败时不能把 task_id 当作 voice_id。

curl --fail-with-body 'https://api.tu-zi.com/v1/general/custom-voices' \
  -H "Authorization: Bearer $TUZI_API_KEY" \
  -F 'voice_name=我的音色' \
  -F 'file=@./sample.wav;type=audio/wav'
curl --fail-with-body 'https://api.tu-zi.com/v1/general/custom-voices' \
  -H "Authorization: Bearer $TUZI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"voice_name":"我的音色","voice_url":"https://example.com/sample.wav"}'
curl --fail-with-body 'https://api.tu-zi.com/v1/general/custom-voices/task_REPLACE_WITH_RESULT' \
  -H "Authorization: Bearer $TUZI_API_KEY"
import os
import time
import requests

base = os.environ.get("TUZI_BASE_URL", "https://api.tu-zi.com").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["TUZI_API_KEY"]}

# Submit once. Save the returned task ID before polling.
with open("sample.wav", "rb") as audio:
    response = requests.post(
        base + "/v1/general/custom-voices", headers=headers,
        data={"voice_name": "My voice"},
        files={"file": ("sample.wav", audio, "audio/wav")}, timeout=120,
    )
response.raise_for_status()
task_id = response.json()["data"]["task_id"]
print("voice task_id:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(
        base + "/v1/general/custom-voices/" + task_id,
        headers=headers, timeout=30,
    )
    response.raise_for_status()
    data = response.json()["data"]
    if data["task_status"] == "succeed":
        voice_id = data["task_result"]["voices"][0]["voice_id"]
        break
    if data["task_status"] == "failed":
        raise RuntimeError(data.get("task_status_msg", "Voice creation failed"))
    time.sleep(5)
else:
    raise TimeoutError("Keep polling the existing task: " + task_id)

print("voice_id:", voice_id, flush=True)
response = requests.post(base + "/v1/videos", headers=headers, json={
    "model": "kling-4.0",
    "contents": [
        {"type": "prompt", "text": "A person says hello using @voice_1."},
        {"type": "voice", "voice_id": voice_id, "id": "voice_1"},
    ],
    "settings": {"duration": 5, "resolution": "720p", "aspect_ratio": "16:9"},
}, timeout=120)
response.raise_for_status()
print("video task:", response.json())
# Query GET /v1/videos/{id} with the ID returned above until completed or failed.

音色创建接口

创建主体并在视频中引用

主体让同一角色或物体在多段视频里保持一致。只接受 JSON:element_name 1–20 字、element_description 1–100 字;image_refer 传 1 张正面图和 1–3 张其他角度图(公网 URL 或 Base64),video_refer 传 1 段 3–8 秒公网视频。可用 element_voice_id 绑定本站音色。查询到 data.task_status=succeed 后读取 data.task_result.elements[0].element_id,放入 contents 的 element 项;只接受本站 element_ ID,不能填可灵数字 ID,task_id 也不是 element_id。

curl --fail-with-body 'https://api.tu-zi.com/v1/general/advanced-custom-elements' \
  -H "Authorization: Bearer $TUZI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "element_name": "兔子",
  "element_description": "白色卡通兔子,红色围巾",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://example.com/front.png",
    "refer_images": [
      {
        "image_url": "https://example.com/side.png"
      }
    ]
  }
}'
curl --fail-with-body 'https://api.tu-zi.com/v1/general/advanced-custom-elements/task_REPLACE_WITH_RESULT' \
  -H "Authorization: Bearer $TUZI_API_KEY"
import os
import time
import requests

base = os.environ.get("TUZI_BASE_URL", "https://api.tu-zi.com").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["TUZI_API_KEY"]}

# Submit once. Save the returned task ID before polling.
response = requests.post(base + "/v1/general/advanced-custom-elements", headers=headers, json={
    "element_name": "Rabbit",
    "element_description": "White cartoon rabbit with a red scarf",
    "reference_type": "image_refer",
    "element_image_list": {
        "frontal_image": "https://example.com/front.png",
        "refer_images": [{"image_url": "https://example.com/side.png"}],
    },
}, timeout=120)
response.raise_for_status()
task_id = response.json()["data"]["task_id"]
print("element task_id:", task_id, flush=True)

deadline = time.monotonic() + 900
while time.monotonic() < deadline:
    response = requests.get(
        base + "/v1/general/advanced-custom-elements/" + task_id,
        headers=headers, timeout=30,
    )
    response.raise_for_status()
    data = response.json()["data"]
    if data["task_status"] == "succeed":
        element_id = data["task_result"]["elements"][0]["element_id"]
        break
    if data["task_status"] == "failed":
        raise RuntimeError(data.get("task_status_msg", "Element creation failed"))
    time.sleep(5)
else:
    raise TimeoutError("Keep polling the existing task: " + task_id)

print("element_id:", element_id, flush=True)
response = requests.post(base + "/v1/videos", headers=headers, json={
    "model": "kling-4.0",
    "contents": [
        {"type": "prompt", "text": "@element_1 runs in the rain."},
        {"type": "element", "element_id": element_id, "id": "element_1"},
    ],
    "settings": {"duration": 5, "resolution": "720p", "aspect_ratio": "16:9"},
}, timeout=120)
response.raise_for_status()
print("video task:", response.json())
# Query GET /v1/videos/{id} with the ID returned above until completed or failed.

主体创建接口

任务结果与下载

保存提交返回的 id 或 task_id。统一视频查询使用 GET /v1/videos/{task_id},等待 queued / in_progress 到 completed 或 failed;完成后读取 video_url(部分响应同时在 metadata.url 提供)。本站相对路径需与调用域名拼接,/content 入口使用本站 Key;外部下载 URL 不携带本站 Key。结果可能过期,请及时下载。网络超时保留任务 ID 继续 GET,不自动重试创建 POST。

统一视频完整 Python / JavaScript 轮询下载示例

常见问题定位

现象检查方式
Error validating image / 图片 URI 错误视频或任务 ID 是否误填到了图片字段;检查媒体 URL 是否返回真实素材
unsupported content type / 字段不支持检查系列、版本和 content/contents/input 的准确类型;不要把音频 URL 填入 voice_id
400 参数冲突检查 prompt 与 input、首尾帧与多参考、秒数与 response_format 的互斥项
HTTP 成功但任务 failed记录本站任务 ID、时间、模型、域名和已脱敏参数;按任务错误定位,不能依据提交 200 宣称成功
404 或不可访问任务确认域名、Key 权限、本站任务类型;不要使用其他站点或官方任务 ID
本地文件无法访问使用系列明确支持的上传方式,或提供可读取的 HTTPS 媒体 URL

资料与适用范围

Kling 4.0 text-to-video

Kling 4.0 image-to-video

Kling 4.0 video-omni

Kling API updates

适用场景

  • 选择视频模型和素材协议
  • 排查参数与任务失败

API 协议

  • /v1/videos

常见问题

拿到 task_id 就代表生成成功吗?

不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。

本地图片、视频和 WAV 能直接填写路径吗?

不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。

能把不同模型的参数和任务 ID 互换吗?

不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。

官方来源

  1. Kling 4.0 text-to-video 官方
  2. Kling 4.0 image-to-video 官方
  3. Kling 4.0 video-omni 官方
  4. Kling API updates 官方