Kling V4

使用模型 kling-v4 在 APIMaster 创建异步视频任务。先在控制台创建 API Key，调用地址为 https://apimaster.ai/v1。

能力对照

能力	kling-v4	kling-v4-flash
文生视频	支持	支持
图生视频	首帧、中间帧、尾帧，最多 10 张	仅一张首帧
Omni 图像参考	首帧、中间帧、尾帧和参考图	首帧和参考图
参考视频、视频编辑	支持	支持
自定义元素、预设元素	支持	支持
音色参考、音色管理	支持	不支持
输出分辨率	720p、1080p，默认 1080p	仅 720p
输出时长	3–30 整数秒	3–20 整数秒
输入视频时长	单条及合计均为 3–30 秒	单条及合计均为 3–20 秒
输出帧率	24 fps	24 fps

本页原生工作流使用 settings、contents、options。既有 /videos/generations 扁平便捷格式继续使用其原有参数与默认值，不能将两套格式混用。Flash 输出上限为 20 秒；V4 上限为 30 秒。

鉴权和接口总表

请求头为 Authorization: Bearer YOUR_APIMASTER_KEY、Content-Type: application/json。提交时建议使用唯一的 Idempotency-Key；响应超时后使用相同 Key 恢复，避免重复付费生成。

以下路径均相对于 https://apimaster.ai/v1，MODEL 替换成 kling-v4。

方法	路径	功能
POST	/kling/MODEL/text-to-video	文生视频
POST	/kling/MODEL/image-to-video	图生视频
POST	/kling/MODEL/omni-video	多模态参考生成、视频编辑
GET	/videos/{task_id}	查询本账号的视频或资源任务
GET	/videos/{task_id}/content	下载已完成视频，需要鉴权
POST	/kling/MODEL/create-element	创建多图元素或视频人物元素
GET	/kling/MODEL/elements	分页列出本账号的元素任务
GET	/kling/MODEL/elements/{resource_id}	查询本账号元素
GET	/kling/MODEL/elements/presets	预设元素库
DELETE	/kling/MODEL/elements/{resource_id}	删除本账号的自定义元素
POST	/kling/kling-v4/create-voice	创建音色，仅 V4
GET	/kling/kling-v4/voices	自定义音色任务列表
GET	/kling/kling-v4/voices/{resource_id}	查询自定义音色
GET	/kling/kling-v4/voices/presets	预设音色库
DELETE	/kling/kling-v4/voices/{resource_id}	删除自定义音色

自定义资源 ID 是 APIMaster 返回的 task_… 句柄，预设资源 ID 带 preset: 前缀。引用和删除时使用返回值，不填写其他账号的原始资源 ID。自定义素材按账号和创建路由隔离，不可跨账号查询或引用；原创建路由不可用时返回错误，不会悄悄替换为其他素材。

生成请求完整参数

字段	类型	必填	说明
model	string	原生路径可省略	提供时必须与 URL 中的 kling-v4 一致
prompt	string	文生视频必填	描述场景、人物、动作、镜头、正向和负向要求；仅用于文生路径
contents	object[]	图生、Omni 必填	按顺序组织素材，必须恰有一个 prompt 项
settings	object	否	输出分辨率、时长、画幅、声音设置，见下表
options	object	否	回调、客户端引用、水印设置
notifications	object	否	APIMaster 已验证任务 Webhook；见回调指南
client_reference_id	string	否	APIMaster 回调中的业务关联值，最多 128 字节

纯英文提示词最多 26,000 字符，纯非英文最多 11,000 字符；混合输入须满足 英文字符数 / 26000 + 非英文字符数 / 11000 <= 1。通过 @id 引用素材，并明确要求保留的外观、动作、背景、音色或镜头节奏。多阶段动作按时间顺序描述。仅在提示词里写素材名称不会自动上传素材。

contents 项

字段	类型	必填条件	说明
type	string	所有项	内容类型，见下表
text	string	prompt	提示词内容
url	string	图像、视频类型	可公开访问的素材 URL；图像还可使用 Base64
id	string	条件必填	当前任务内唯一，通过 @id 引用；元素和音色必填，V4 多张中间帧或多张参考图也须提供
element_id	string	element	本账号元素句柄或返回的预设 ID
voice_id	string	voice	本账号音色句柄、元素绑定音色句柄或预设 ID；仅 V4

type	用途	图生视频	Omni
prompt	生成描述	必须	必须
first_frame	固定首帧	两模型	两模型
middle_frame	按时间顺序给中间帧	仅 V4	仅 V4
last_frame	固定尾帧	仅 V4	仅 V4
refer_image	外观、主体、背景、风格参考，不锁定帧	不支持	两模型
feature_video	动作、镜头、节奏参考	不支持	两模型
base_video	待编辑视频	不支持	两模型，最多一条
element	持久的人物、物品、场景元素	不支持	两模型
voice	音色参考	不支持	仅 V4

首帧图须位于所有图像之前，尾帧图须位于所有图像之后。中间帧按出现顺序排列。Flash 不支持中间帧和尾帧。

settings

字段	类型	必填	取值、默认值和约束
resolution	string	否	720p 或 1080p，默认 1080p
duration	integer	否	3–30 秒；显式参数优先于提示词中的时长
aspect_ratio	string	否，仅文生和 Omni	21:9、16:9、9:16、1:1、4:3、3:4；Omni 额外支持 adaptive。文生默认 16:9，Omni 默认 adaptive；图生按图片输入确定
audio	string	否，仅 Omni	native 默认生成匹配音频；original 保留源视频音频

original 必须提供 base_video 或 feature_video；优先取 base_video 的音频，否则取第一条 feature_video 的音频，不能同时引用音色。原生格式不提供 audio=false 静音开关。

省略 duration 时，优先采用提示词明确指定的时长；提示词也没有指定时，Omni 存在 base_video 则按其时长四舍五入取整，否则默认 10 秒。最终输出计费时长使用任务用量回执，而不是直接把下载后的视频容器时长当成计费时长。

Omni 采用 adaptive 时，先识别提示词中明确的画幅；没有时依次参考 base_video、关键帧（首帧优先）、单条 feature_video。多条 feature_video 或没有适用素材时默认 16:9。显式传入非 adaptive 的画幅优先于提示词画幅。

options

字段	类型	必填	说明
callback_url	string	否	原生任务状态回调地址；需要 APIMaster 公共任务 ID 和投递记录时使用 notifications
external_task_id	string	否	客户端关联值；查询时使用返回的 task ID，安全重试使用 Idempotency-Key
watermark_info	object	否	是否同时生成带水印版本
watermark_info.enabled	boolean	否	默认 false；显式 false 会保留，true 请求额外水印结果；不支持自定义水印图案

素材限制

类别	限制
生成图像	JPG/JPEG/PNG，每张最多 30 MB，宽高至少 300px，比例 2:5–5:2，最多 10 张
生成输入视频	MP4/MOV，每条最多 300 MB，宽高分别为 700–4553px，总像素面积不超过 8,294,400，24–60fps，比例 2:5–5:2
V4 输入时长	每条及归一化后合计均为 3–30 秒
Flash 输入时长	每条及归一化后合计均为 3–20 秒
视频数量	参考视频与视频人物元素合计最多 5 个，base_video 最多 1 条
元素数量	最多 7 个，视频人物元素最多 3 个
音色数量	最多 3 个，仅 V4
总素材数量	图像、视频、元素和音色合计最多 15 个，prompt 不计入

视频人物元素会占用视频数量并贡献输入视频时长。元素创建的图像限制与生成图像不同，见后文。URL 须在任务素材摄取期间保持可访问，不能依赖 Cookie 或登录。

调用示例

文生视频

curl "https://apimaster.ai/v1/kling/kling-v4/text-to-video" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{"prompt":"A paper boat floats on a quiet pond, gentle water sounds.","settings":{"duration":3,"resolution":"720p","aspect_ratio":"16:9"},"options":{"watermark_info":{"enabled":false}}}'

图生视频

向 POST https://apimaster.ai/v1/kling/kling-v4/image-to-video 提交：

{
  "contents":[
    {"type":"prompt","text":"Start from @first. Slowly move the camera toward the subject."},
    {"type":"first_frame","url":"https://YOUR_PUBLIC_HOST/first.jpg","id":"first"}
  ],
  "settings":{"duration":5,"resolution":"720p"}
}

V4 可继续加入 middle_frame 和 last_frame；Flash 只能提供一张 first_frame。

Omni 编辑与多模态参考

向 POST https://apimaster.ai/v1/kling/kling-v4/omni-video 提交：

{
  "contents":[
    {"type":"prompt","text":"Edit @source. Replace the main object with @object, preserve camera movement and background."},
    {"type":"base_video","url":"https://YOUR_PUBLIC_HOST/source.mp4","id":"source"},
    {"type":"refer_image","url":"https://YOUR_PUBLIC_HOST/object.png","id":"object"}
  ],
  "settings":{"duration":5,"resolution":"720p","aspect_ratio":"adaptive","audio":"original"}
}

仅参考镜头或动作而不编辑源视频时，把 base_video 改成 feature_video 并明确用途。引用元素时添加 {"type":"element","element_id":"task_YOUR_ELEMENT","id":"character"}，提示词中用 @character 指定主体。

元素管理

向 POST https://apimaster.ai/v1/kling/kling-v4/create-element 提交。创建是异步任务；完成后把返回的 resource.element_id 用于 Omni 引用。预设库元素无需创建。

字段	类型	必填条件	说明
element_name	string	必填	1–20 字符
element_description	string	必填	1–100 字符
reference_type	string	必填	image_refer 多图元素，或 video_refer 视频人物元素
element_image_list	object	image_refer	正面图与其他参考图
element_image_list.frontal_image	string	图像元素	正面图 URL 或 Base64
element_image_list.refer_images	object[]	图像元素	1–3 张不同角度或细节图，不与正面图重复
element_image_list.refer_images[].image_url	string	每张参考图	图像 URL 或 Base64
element_video_list	object	video_refer	视频人物素材，不与图像素材字段混用
element_video_list.refer_videos	object[]	视频元素	恰好 1 条
element_video_list.refer_videos[].video_url	string	每条视频	MP4/MOV 公共 URL
element_voice_id	string	否	绑定已有的自定义或预设音色；图像元素绑定音色仅适用于人物/类人元素
tag_list	object[]	否	元素分类
tag_list[].tag_id	string	每个标签	o_101 热门、o_102 人物、o_103 动物、o_104 物品、o_105 服装、o_106 场景、o_107 特效、o_108 其他
callback_url	string	否	原生任务回调
external_task_id	string	否	客户端关联值；轮询使用返回的公共 task ID

创建元素的图像须为 JPG/JPEG/PNG，每张最多 10 MB，宽高至少 300px，比例 1:2.5–2.5:1。视频人物素材仅支持写实类人角色：3–8 秒、1080p、16:9 或 9:16、MP4/MOV、最多 200 MB。视频含人声时可能自动定制并绑定音色，返回的绑定音色句柄以 .voice 结尾。

{
  "element_name":"Blue mascot",
  "element_description":"A fictional blue mascot from multiple angles",
  "reference_type":"image_refer",
  "element_image_list":{
    "frontal_image":"https://YOUR_PUBLIC_HOST/front.png",
    "refer_images":[{"image_url":"https://YOUR_PUBLIC_HOST/side.png"}]
  },
  "tag_list":[{"tag_id":"o_104"}]
}

自定义列表：GET …/elements?pageNum=1&pageSize=30，pageNum 为 1–1000、pageSize 为 1–500。预设列表：GET …/elements/presets。查询资源：GET …/elements/task_YOUR_ELEMENT。删除自定义元素：DELETE …/elements/task_YOUR_ELEMENT；预设元素不可删除，删除不清除历史视频或消费记录。

音色管理，仅 V4

Flash 不支持音色参考、音色创建、音色库接口。V4 使用 POST https://apimaster.ai/v1/kling/kling-v4/create-voice。

字段	类型	必填条件	说明
voice_name	string	必填	1–20 字符
voice_url	string	来源	MP3/WAV 或 MP4/MOV，干净的单人声音，5–30 秒
video_id	string	可选替代来源	符合旧版资格且属于本账号的 V2.6 开声视频、Avatar 或口型同步视频；不接受无归属的原始 ID。没有可用旧版视频时使用 voice_url
callback_url	string	否	原生任务回调
external_task_id	string	否	客户端关联值

来源须二选一。当前原生工作流直接支持 voice_url；video_id 须经受支持的旧版视频工作流验证归属和资格，不能把任意 V4 视频 ID 当作旧版合格来源。

{"voice_name":"Narrator","voice_url":"https://YOUR_PUBLIC_HOST/voice.wav"}

轮询成功后，使用 resource.voice_id。在 V4 Omni 中添加 {"type":"voice","voice_id":"task_YOUR_VOICE","id":"speaker"} 并在提示词中使用 @speaker。声音设置为 native，不可与 original 混用。

GET …/voices?pageNum=1&pageSize=30 列出本账号音色任务；GET …/voices/presets 获取预设库；GET …/voices/{resource_id} 查询；DELETE …/voices/{resource_id} 删除。pageNum 和 pageSize 均为 1–1000。预设音色不可删除，删除自定义音色不清除历史记录。

任务、下载与错误

创建成功返回公共任务 ID：

{"id":"task_EXAMPLE","task_id":"task_EXAMPLE","object":"video","model":"kling-v4","status":"queued"}

同一账号携带 API Key 轮询 GET https://apimaster.ai/v1/videos/task_EXAMPLE。状态为 queued、in_progress、completed、failed。视频完成后返回鉴权下载 URL；元素和音色任务返回带本账号资源句柄的对象。资源列表也包含仍在处理或失败的创建任务。

curl "https://apimaster.ai/v1/videos/task_EXAMPLE" -H "Authorization: Bearer $APIMASTER_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_EXAMPLE/content" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" -o output.mp4

建议每 3–5 秒轮询并适当退避。不要因为任务尚未完成就重新生成。提交超时后使用原 Idempotency-Key 恢复；同一个 Key 改变请求体会被拒绝。下载链接有有效期，完成后请及时保存视频。

情况	处理
参数、类型、模型与路径冲突	HTTP 400，修正后再提交
Key 无效、模型权限不足	检查账号与模型访问权限
资源不存在、属于其他账号	拒绝访问或引用
素材无法读取、签名 URL 失效	修复可访问性，按失败状态决定是否重新提交
频率或并发限制	退避，已受理任务继续轮询，不重复创建
已受理任务最终失败	状态 failed，进入正常任务退款流程
视频完成而用量/回执尚未就绪	继续轮询，待最终用量可验证后结算

计费

当前售价以模型卡和账号实际折扣为准。图像参考、图像元素、音色不自动计入输入视频；视频人物元素需要计入。

无视频输入：计费秒数 = 输出计费时长
有视频输入：计费秒数 = 输出计费时长 + max(输入计费时长, 输出计费时长)

有视频输入采用单独的每秒费率。输入视频时长包括 feature_video、base_video、视频人物元素，经系统归一化后可能与源文件略有不同。短输入视频也可能按输出时长两倍计费，不能只看输出长度估算费用。

网关先预扣，再按完成回执中的用量结算，退回多余预扣。省略 duration 时模型可能从提示词决定时长，因此预扣值可能大于实际费用。元素创建、音色创建是独立操作，不应误算为视频时长；音色创建按次计费，视频折扣不代表音色创建也享受相同折扣。

最终实扣与视频预览请查看控制台消费日志。成功响应和视频可播放属于功能交付证据，不等于独立模型身份指纹验证。

---

请求了带水印版本时，可使用 GET /v1/videos/{task_id}/content?watermark=true 下载该版本；普通 content 端点返回原始版本，两者均需认证。

既有便捷接口

使用 kling-v4 调用文生视频、图生视频、参考生视频、视频编辑和视频续写。支持 720p / 1080p，每个新增片段 3–30 秒，始终包含立体声音轨。

Base URL： https://apimaster.ai/v1。当前接口所有生成模式都应提供非空 prompt。无提示词图生经实测会被拒绝；请描述期望的运动或运镜。每次请求都使用 Authorization: Bearer YOUR_API_KEY。素材链接必须公开可下载，无需登录、Cookie 或防盗链鉴权。

提交、查询与下载

向 POST https://apimaster.ai/v1/videos/generations 发送 JSON，设置 Content-Type: application/json。

curl "https://apimaster.ai/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v4","prompt":"一只纸船在平静池塘上缓缓漂流，水波轻荡，伴随轻柔水声。","duration":3,"resolution":"720p","aspect_ratio":"16:9"}'

{"id":"task_example","task_id":"task_example","object":"video","model":"kling-v4","status":"queued","created_at":1792756800}

拿到任务 ID 仅代表请求已接收。每隔 10–20 秒调用 GET https://apimaster.ai/v1/videos/{task_id}，直到 status 为 completed 或 failed。中间状态包括 queued、in_progress。成功后返回需鉴权的 APIMaster 视频地址；请使用同一 API key 尽快下载：

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o kling-v4.mp4

失败时查看 error.code、error.message，修正请求后重新提交。成功生成的视频也可在控制台用量日志中预览和下载。

完整请求参数

参数	类型	必填 / 默认值	说明
model	string	必填	固定 kling-v4。
prompt	string	必填（含图生视频）	描述画面、动作、运镜及声音。参考模式可用 @Image1、@Video1、@Audio1，按各类素材数组顺序从 1 编号；编辑模式输入视频为 @Video1。
duration	integer	默认 5	生成时长 3–30 秒。编辑不传时跟随输入视频时长，向上取整且最多 30 秒；续写表示新增片段时长。
resolution	string	720p	支持 720p、1080p，不使用 mode。
aspect_ratio	string	随模式变化	16:9、9:16、1:1、21:9；参考模式额外支持 auto。文生默认 16:9，图生与编辑跟随输入，参考默认 auto；续写禁止传入。
image_urls	string[]	可选	图生：第 1 张首帧、第 2 张尾帧，最多 2 张。参考或编辑：最多 10 张参考图。仅用参考图生成时显式传 omni_reference_task_type: "reference"。
image_with_roles	object[]	可选	图片角色数组，每项包含 url 和 role。图生模式勿将 image_urls 与显式首尾帧字段混用。
image_with_roles[].url	string	每项必填	公开 HTTP(S) 图片地址。
image_with_roles[].role	string	每项必填	first_frame、last_frame、keyframe（也接受 middle_frame）、reference_image。
first_frame_image	string	可选	首帧地址，也可通过 image_urls 第 1 张或 first_frame 角色提供。
last_frame_image	string	可选	图生尾帧或续写的目标尾帧地址。
video_urls	string[]	可选	参考模式最多 5 段视频、总输入时长最多使用 30 秒；编辑或续写可用恰好 1 条代替 video_url，必须显式指定任务类型。
video_url	string	编辑 / 续写必填，或用 video_urls	输入视频，必须同时指定 edit 或 extend，勿与 video_urls 同传。编辑视频至少 3 秒，超过 30 秒取前 30 秒。
audio_urls	string[]	仅参考模式可选	最多 3 段参考音频，每段 5–30 秒。
omni_reference_task_type	string	auto	auto、reference、edit、extend；auto 按素材自动选择文生、图生或参考模式。
audio_setting	string	随模式变化	origin 保留原声，auto 重新配声。仅支持编辑或带参考视频的参考模式；编辑默认保留原声，参考默认重新配声；续写禁止传入。

图生模式必须恰好 1 张首帧，最多 1 张尾帧、8 张中间帧、10 张总图，中间帧按数组顺序使用。参考模式最多 10 张图片、5 段视频、3 段音频，合计 15 个素材。参考模式使用 reference_image 角色；编辑参考图使用 image_urls。续写除输入视频外只接受可选目标尾帧。

兼容别名：seconds 对应 duration，size 对应分辨率（720p / 1080p），ratio 对应 aspect_ratio。别名与标准字段冲突时返回 HTTP 400。建议直接使用表中的标准字段。

各模式示例

图生视频：

{"model":"kling-v4","prompt":"Slow camera movement, gentle motion.","image_urls":["https://example.com/start.png","https://example.com/end.png"],"duration":5}

首帧、中间帧、尾帧：

{"model":"kling-v4","prompt":"Animate smoothly through the supplied frames.","image_with_roles":[{"url":"https://example.com/start.png","role":"first_frame"},{"url":"https://example.com/middle.png","role":"keyframe"},{"url":"https://example.com/end.png","role":"last_frame"}],"duration":10}

参考生视频：

{"model":"kling-v4","prompt":"让 @Image1 中的角色跟随 @Video1 的运镜，背景音乐参考 @Audio1。","image_with_roles":[{"url":"https://example.com/character.png","role":"reference_image"}],"video_urls":["https://example.com/camera.mp4"],"audio_urls":["https://example.com/music.mp3"],"omni_reference_task_type":"reference","aspect_ratio":"auto","duration":5}

视频编辑，不传时长和比例时跟随输入视频：

{"model":"kling-v4","prompt":"将画面改为下雪的冬夜。","omni_reference_task_type":"edit","video_url":"https://example.com/input.mp4","image_urls":["https://example.com/style.png"],"audio_setting":"origin"}

视频续写，返回原视频与新增片段拼接的完整视频：

{"model":"kling-v4","prompt":"镜头继续向前推进，天色渐暗。","omni_reference_task_type":"extend","video_url":"https://example.com/input.mp4","duration":5,"last_frame_image":"https://example.com/target.png"}

示例素材地址是占位符，请替换为实际可公开访问的图片、视频或音频。

计费与退款

官方基础价（核查于 2026-10-23）

Kling 开发者定价页切换到 Balance 后列出以下预览价，作为模型基础参考价；实际渠道与账户价格以模型卡为准。官方页面将其直连接口标为 Coming Soon，APIMaster 的可用状态以自身模型卡为准。

档位	基础价 USD / 计费秒
720p，无视频输入	$0.157
1080p，无视频输入	$0.235
720p，有视频输入	$0.094
1080p，有视频输入	$0.141

按计费秒数收费，720p、1080p 分别定价。编辑与带参考视频的参考生成使用视频输入档单价。最新价格与可用路由见 Kling V4 模型卡，最终扣费还受渠道与账户系数影响，以用量日志为准。

模式	计费秒数
文生、图生、仅含图片或音频的参考生成	输出秒数
视频续写	新增片段秒数，不重复收取原视频时长
编辑、带参考视频的参考生成	输出秒数 + max(输出秒数, 输入视频秒数)

输入视频时长先求和，再向上取整，最多计 30 秒。例如编辑 3.04 秒的视频且不传 duration，输出为 4 秒，按视频输入档计 8 秒。给 20 秒视频续写 5 秒，即使返回文件为 25 秒，也只按新增的 5 秒计费。

编辑与参考视频模式在提交前由服务器测量输入视频；探测失败会在生成扣费前拒绝请求。生成任务失败退回预扣的生成费用；无效参数不收费。反复查询已完成任务不会重复收取生成费。

不支持的参数与排错

V4 始终包含立体声。不要传 mode、negative_prompt、multi_shot、multi_prompt、element_list、video_list、camera_control、voice_list 及其他未列出的字段。audio: false、watermark: true 不支持；audio: true、watermark: false 作为兼容值接受。audio_setting 仅在支持的模式下使用。

错误	处理方法
HTTP 400 / 参数无效	检查 JSON 类型、素材数量、任务模式和字段组合；duration 必须是 JSON 整数。
无法测量输入视频时长	换成可公开下载、无鉴权和防盗链限制的有效 MP4 / MOV 地址。
传 video_url 但未指定编辑或续写	参考模式改用 video_urls；单数 video_url 必须指定 edit / extend。
HTTP 503 / 价格不可用	当前档位不可用，请查看模型卡。
异步生成失败	查看任务错误，检查素材后修正重试；生成预扣费用退回。

注册账户后创建 API Key，使用 https://apimaster.ai/v1 与模型 ID kling-v4 调用。