跳转到主要内容
POST
使用 kling-v4-image 调用 POST /v1/images/generations 异步提交任务,从 data[0].task_id 获取任务 ID,再通过 GET /v1/tasks/{task_id} 查询结果。

认证

string
必填
使用 Authorization: Bearer <token>,其中 <token> 为你的 APIMart API Key。

请求参数

string
必填
固定为 kling-v4-image。
boolean
默认值:"false"
是否在提交图片任务前执行内容审核。
  • true:使用 omni-moderation-latest 审核提示词和输入图片
  • false 或不传:不发起审核请求,不增加审核成本与延迟(默认)
string
必填
文生图、图生图和组图均必填,可同时描述希望出现和希望避免的内容。纯英文最多 50,000 字符,纯中文等最多 21,000 字符;混合语言按比例计算。
string[]
最多 10 张参考图,使用公网可访问的图片直链。本地文件可先通过图片上传接口上传,再传返回的 url。支持 JPG / JPEG / PNG / GIF,单张不超过 30 MB,宽、高均至少 300 px,宽高比在 2:5–5:2 之间。提交时会检查参考图:链接返回 HTTP 403 / 404 / 410、任一边不足 300 px、宽高比超出 2:5–5:2,或单张超过 30 MB,均直接返回 HTTP 400,不创建任务、不扣生成费用。源站超时等其他取图失败会先受理,随后任务失败并全额退回预扣生成费用。提示词可用 @Image1、@Image2 等按数组顺序引用图片;不写这些标记也会参考输入图片。
integer
默认值:"1"
普通生成的输出张数,整数 1–9,默认 1。组图模式可以省略 n 或传 1,实际张数由 sequential_image_generation_options.max_images 指定;组图时传 n > 1 返回 HTTP 400。
string
默认值:"2K"
支持 2K(默认)、4K 和 8K,不区分大小写,输出 PNG。比例为 1:1 时,2K 为 2048×2048,4K 为 4096×4096,8K 为 8192×8192;其他比例的实际宽高以返回图片为准。8K 同样支持文生图、图生图和组图:普通生成一次 1–9 张,组图 2–4 张,最多 10 张参考图。参考图的格式、尺寸和单张 30 MB 上限保持不变。
string
默认值:"auto"
输出宽高比,支持 auto(默认)和以下 8 种指定比例:16:9、9:16、1:1、4:3、3:4、3:2、2:3、21:9。auto 根据提示词内容或参考图决定比例。不支持 2048x2048 等像素尺寸写法。
string
size 的别名,支持相同取值。两者同时传入时,以 aspect_ratio 为准。
string
默认值:"disabled"
disabled 或省略表示普通生成;设为 auto 时生成一组内容关联的图片,并必须提供 sequential_image_generation_options.max_images。这里的 auto 不表示自动决定图片张数。
object
组图模式下通过此对象指定张数。
不支持 width、height、mask_url、像素形式的 size 或 watermark: true,传入时返回 HTTP 400。

请求示例

以下请求均发送到 POST /v1/images/generations。请将示例图片地址替换为实际可访问的直链。

图生图

一次生成 3 张 4K 图片

生成一张 8K 图片

生成 4 张 8K 关联组图

组图使用 max_images 指定 2–4 张;n 可省略或传 1,不能大于 1。组图可能需要几分钟,请保留 task_id 并持续查询,避免重复提交。

8K 输出与耗时参考

以下为测试环境的实测样本,尺寸、文件大小和耗时仅供参考,以实际返回为准。 建议每 5–10 秒查询一次任务,直到 completed 或 failed。estimated_time 固定返回 60 秒,不能用作实际完成时间或倒计时;请保留 task_id,避免因等待较久而重复提交。 8K 返回 PNG 原图,单张文件可能超过 100 MB。列表或预览建议使用自行生成的缩略图,或按需懒加载;提供原图下载入口,并提醒用户文件较大。

查询任务

通过任务查询接口读取 data.status:pending / processing 表示处理中,completed 表示成功,failed 时读取 data.error.message。
以下为成功结果的结构示意。图片地址位于 data.result.images[].url[],其中 url 是数组;请遍历获取所有输出,并及时下载保存。

计费

按实际生成张数和所选分辨率档位计费,参考图另外按张计费。具体单价以价格页为准。
  • 普通生成 n=3 按 3 张输出计费;组图按实际返回张数计费。
  • 每张参考图在每次请求中只计算一次,不随输出张数翻倍。例如 2 张参考图生成 3 张图片,计 2 张输入和 3 张输出。
  • 生成失败的任务不收费,预扣生成费用全额退回。

常见参数错误

以下参数错误在提交时同步返回 HTTP 400,不创建任务、不扣生成费用。提交失败时读取 error.message;任务创建后失败时读取 data.error.message。