API 协议
Kling 4.0:参数、场景与调用指南
预览指南
粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。
直接答案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;此流程需接口上线,未完成音色创建验收。 |
| 音色 ID | contents[].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 及带音色生成尚未完成线上验收。
| 字段 | 类型 | 用法与限制 |
|---|---|---|
Authorization | header string | 必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。 |
model | string | 必填 kling-4.0;不将标准版参数套到 Flash 或旧版。 |
prompt | string | 本站纯文本快捷方式,与 contents 二选一,转换为 type=prompt 的内容项。 |
contents | object[] | 必须含 prompt 项。文本及素材数组;素材总数最多 15,图片 ≤10、视频 ≤5、主体 ≤7、音色 ≤3;视频主体也占用视频配额。 |
contents[].type | string | 每项必填:prompt/first_frame/middle_frame/last_frame/refer_image/feature_video/base_video/element/voice。middle_frame 和 base_video 依赖支持该模式的本站渠道,不是所有渠道都接收。 |
contents[].text | string | prompt 项必填;本站校验英文最多 26000 字符、非英文最多 11000 字符,混合按比例计;引用素材用 @id。 |
contents[].url | string | 帧、图片、视频项使用;图片支持 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[].id | string | 提示词中的素材引用名,非空且在请求内唯一;多个中间帧、参考图需分别命名,voice/element 必填。 |
contents[].element_id | string | element 必填。使用本人可访问的本站主体 ID;创建并查询成功后使用,不是本次引用名 id。 |
contents[].voice_id | string | voice 必填。使用创建成功的本站音色 ID;不能填音频 URL,音色创建流程及已知可用性限制见音色指南。 |
settings.duration | integer | 3–30 秒;本站省略时显式发送 10,不依赖提示词推断时长。 |
settings.audio | string | 可选 native(默认,同步生成声音)/original(保留输入视频声音)。original 必须包含 base_video 或 feature_video,且不能同时传 voice;优先使用 base_video,否则用第一个 feature_video。已支持参数校验和转发,音轨效果仍需真实生成验收。 |
settings.resolution | string | 720p/1080p;本站默认 1080p。不要把创作端 4K 宣传当作当前本站 API 枚举。 |
settings.aspect_ratio | string | 支持 adaptive/16:9/9:16/1:1/21:9/4:3/3:4;adaptive 用于支持它的参考模式。与 size 同时指定时不能冲突。 |
options.watermark_info.enabled | boolean | 可选水印开关;本站兼容顶层 watermark,不要传冲突值,显式 false 保留。 官方默认 false,不支持自定义水印。 |
options.external_task_id | string | 可选业务关联标识,不提供创建请求幂等保证。 官方要求在同账号内唯一,不替换服务生成的任务 ID。 |
options.callback_url | string | 可选 HTTP(S) 回调地址。支持的渠道可能转为顶层 callback_url;保持主动查询,不假定回调返回本站 ID。 |
seconds / size / watermark | site 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 |
资料与适用范围
适用场景
- 选择视频模型和素材协议
- 排查参数与任务失败
API 协议
/v1/videos
常见问题
拿到 task_id 就代表生成成功吗?
不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。
本地图片、视频和 WAV 能直接填写路径吗?
不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。
能把不同模型的参数和任务 ID 互换吗?
不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。
兔子API