可灵生图

项目	值
Base URL	`https://api.hop-base.com/v1`
提交生图任务	`POST /v1/images/generations`
查询任务	`GET /v1/video/tasks/{task_id}`
分组	「可灵模型分组（官方）」

可灵生图全部是异步任务：提交返回 202 与任务 id，再轮询查询接口，完成后从 outputs[] 取图片地址。

可用型号

型号	模型 ID	画质档 `quality`	参考图	官方价
可灵生图 3.0	`kling-image-v3`	1k / 2k	0–1 张	$0.0294/ 张
可灵生图 3.0 Omni	`kling-image-v3-omni`	1k / 2k / 4k	0–10 张	$0.0294起/ 张
可灵生图 O1	`kling-image-o1`	1k / 2k / 4k	0–10 张	$0.0294起/ 张
可灵生图 2.1（文生图）	`kling-image-v2-1`	1k / 2k	不接受	$0.0147/ 张
可灵生图 2.1（图生图）	`kling-image-v2-1-i2i`	1k / 2k	恰好 1 张	$0.0294/ 张
可灵生图 2.1（多图参考）	`kling-image-v2-1-multi-ref`	1k / 2k	2–4 张	$0.0588起/ 张
可灵扩图	`kling-image-expand`	1k	恰好 1 张	$0.0294/ 张

选型建议：纯文生图选 2.1（文生图），要 4k 或多张参考图选 3.0 Omni 或 O1，向四周扩展原图选可灵扩图。

请求参数

参数	必填	类型与限制	默认	说明
`model`	必填	字符串	—	生图模型 ID，见上表
`prompt`	无图片时必填	字符串	—	与非空 `images` 至少其一
`quality`	可选	`1k` / `2k` / `4k`	`1k`	画质档，按型号可选
`n`	可选	整数 1–9	`1`	产出张数
`images`	按型号	数组，每项 `url` / `file_id`	—	参考图或待扩展的原图
`extra`	仅扩图	对象，四个扩展比例	—	见下文扩图

只接收上表字段，表外字段（如 size、aspect_ratio、response_format）一律返回 400。
model 传视频型号返回 400。
quality 不区分大小写，OpenAI 风格的 high、standard 等会被拒绝。
n 按实际产出张数计费。
其他生图型号传非空 extra 返回 400。

参考图

每个 images[] 项必须且只能提供 url 或 file_id 其中之一，且不能带 usage：

{
  "model": "kling-image-v3-omni",
  "prompt": "把两张图里的杯子摆在同一张木桌上",
  "quality": "2k",
  "images": [
    { "url": "https://cdn.example.com/cup-a.png" },
    { "file_id": "your-file-id" }
  ]
}

url 必须是公网可访问的绝对 http:// 或 https:// 地址。
空字符串、相对路径、file:// 等非 HTTP(S) 协议、内网或回环地址、带认证信息的 URL 都会被同步拒绝。
file_id 必须是当前密钥可用的可灵素材，不是 Seedance 素材 ID。
参考图张数按型号限制，见可用型号。

扩图

kling-image-expand 把一张图向四周扩展，比例写在 extra 里：

{
  "model": "kling-image-expand",
  "images": [{ "url": "https://example.com/input.png" }],
  "extra": {
    "left_expansion_ratio": 0.5,
    "right_expansion_ratio": 0.5,
    "up_expansion_ratio": 0,
    "down_expansion_ratio": 0
  }
}

4 个比例均为 0–2 的数字，省略为 0。
四个比例不能全为 0。
扩展后面积不超过原图 3 倍：(1+左+右) × (1+上+下) ≤ 3。

返回结果

提交成功返回 HTTP 202，任务 ID 在顶层 id，形如 kt57x<task-id>：

{
  "id": "ktEXAMPLE",
  "object": "image.generation.task",
  "model": "kling-image-v3",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "img_1k",
  "requested_images": 1
}

用这个 id 轮询 GET /v1/video/tasks/{task_id}。完成后的查询结果：

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "kling-image-v3",
  "status": "completed",
  "progress": 100,
  "created": 1790000000,
  "outputs": [
    "https://api.hop-base.com/example-signed-image.png"
  ],
  "usage": { "bucket": "img_1k", "billed_images": 1 }
}

字段	类型	说明
`id`	string	HopBase 任务 ID，提交与查询相同
`object`	string	提交为 `image.generation.task`，查询为 `video.generation.task`
`status`	string	`queued` → `processing` → `completed` 或 `failed`
`progress`	integer	进度百分比，仅查询返回
`requested_images`	integer	请求的张数，仅提交返回
`billing_bucket`	string	画质对应的计费档，仅提交返回
`outputs`	string[]	图片地址数组，仅 `completed` 时返回
`usage.billed_images`	integer	实际计费张数，等于实际产出张数
`error.code` / `error.message`	string	仅 `failed` 时返回，见任务失败

只有 completed 与 failed 是终态，其他任何值都按进行中处理。

任务结束后，查询响应根对象的 usage 还会带 cost（本任务从余额实际扣除的金额，未扣费的失败为 0）与币种 currency。

示例

提交一个文生图任务，轮询到结束后下载第一张图：

# 1. 提交
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-v3",
    "prompt": "阳光下木桌上的一把陶瓷茶壶",
    "quality": "1k",
    "n": 1
  }'

# 2. 用返回的 id 查询，直到 status 为 completed 或 failed
curl https://api.hop-base.com/v1/video/tasks/ktYOUR_TASK_ID \
  -H "Authorization: Bearer sk-你的密钥"

注意事项

图片地址在 api.hop-base.com 下，自任务完成起 6 小时有效，请及时下载保存。
再次查询返回同一地址、不会续期，过期访问返回 410。
任务创建 2 小时后仍未结束即判为失败、不计费，任务不支持取消。
可灵生图不做余额预留，只在余额小于等于 0 时才会被拦截。
正式产生付费任务前，先用 GET /v1/models 确认当前密钥实际返回的模型 ID。

常见报错

提交阶段出错不会创建任务，也不计费，原因写在 error.message 里：

报错	改法
`request body does not match the JSON contract: json: unknown field "size"`	删掉表外字段，画质用 `quality`
`prompt and input images cannot both be empty`	补 `prompt` 或参考图
`images[0] must provide exactly one of url or file_id`	每项只留 `url` 或 `file_id`
`images[0].url must be a publicly accessible absolute http(s) URL`	换成公网 HTTP(S) 地址
`model "kling-image-v3" does not support quality tier "4k"`	换该型号支持的画质档
`model "kling-image-v2-1-multi-ref" requires 2 to 4 input images`	按型号要求调整参考图张数
`model "<模型 ID>" is not an image model in this catalog`	用 `GET /v1/models` 核对 ID（404）

# 行是触发条件，下一行是 error.message 原文：

# 出现表外字段
request body does not match the JSON contract: json: unknown field "<字段名>"

# prompt 与 images 都为空
prompt and input images cannot both be empty

# images[] 某项 url / file_id 都没有或都有
images[<序号>] must provide exactly one of url or file_id

# url 不是公网 http(s) 绝对地址
images[<序号>].url must be a publicly accessible absolute http(s) URL

# images[] 带了 usage
images[<序号>].usage is not part of the image generation API; remove this field

# 该型号没有这个 quality 档
model "<模型 ID>" does not support quality tier "<值>"

# n 不在 1–9
n must be between 1 and 9, got <值>

# 参考图超过型号上限
model "<模型 ID>" accepts at most <上限> input images, got <张数>

# kling-image-v2-1 带了图片
model "kling-image-v2-1" is a text-to-image model and does not accept input images

# kling-image-v2-1-i2i 不是 1 张图
model "kling-image-v2-1-i2i" requires exactly 1 input image

# kling-image-v2-1-multi-ref 不是 2–4 张图
model "kling-image-v2-1-multi-ref" requires 2 to 4 input images

# 非扩图型号带了 extra
model "<模型 ID>" does not accept unverified extra parameters

# 扩图不是 1 张图
image expansion requires exactly 1 input image

# 扩图 extra 含四个比例以外的键
extra.<键> is not a verified parameter of the image expansion API

# 扩图比例不是 0–2 的数字
extra.<键> must be a number between 0 and 2

# 四个比例全为 0
the four expansion ratios cannot all be 0

# 扩图后面积超过原图 3 倍
expanded area cannot exceed 3x the original image

# 生图模型 ID 不在目录（404）
model "<模型 ID>" is not an image model in this catalog

任务失败

任务失败时查询接口仍返回 HTTP 200，status 为 failed。请按错误码 error.code 分支处理，并把错误说明展示给用户。较早失败的任务可能没有错误码。

情况	`error.code`
提示词或参考图未通过审核	`input_sensitive`
产出被审核拦下	`safety_rejected`
并发已满	`rate_limited`
模型版本已下架	`unsupported_model`
提示词过长，或参数、素材不合规	`invalid_request`
参考图读取失败	`reference_input_invalid`
生成失败或中途被终止	`generation_failed`
创建 2 小时后仍未结束	`timeout`
任务结束但没有产出	`no_output`

# input_sensitive
the prompt was rejected by content moderation; rephrase it and submit again
the reference image was rejected by content moderation; replace it and submit again
the prompt or reference image was rejected by content moderation; revise it and submit again

# safety_rejected
the generated result was blocked by content moderation; adjust the prompt or reference media and submit again

# rate_limited
this model is at its concurrency limit right now; please retry shortly

# unsupported_model
this model version is no longer available; switch to another model and submit again

# invalid_request
the prompt is too long for this model (at most 2500 characters); shorten it and submit again
the request was rejected as invalid by the model; check the parameters and media against the documented limits, then submit again

# reference_input_invalid
a reference image or video is missing or could not be read; make sure every URL is publicly reachable and points to a supported file, then submit again

# generation_failed
image generation failed; please retry, and contact support with the task ID if it keeps failing
image generation was stopped before it finished; please retry, and contact support with the task ID if it keeps failing
… contact support with the task ID

# timeout
task did not reach a billable terminal state within 2 hours; polling stopped

# no_output
image generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing

计费

可灵生图按实际产出张数计费，单价看型号与画质档；失败的任务与轮询查询都不计费。各型号价格见上表的模型卡，你的实际单价以登录后的模型广场为准。

下一步

图片生成 API：各图片系列总览
GPT Image、Gemini 生图、Seedream、Grok Imagine 生图：其他图片系列
可灵视频：可灵视频、动作控制、数字人与对口型
生成图片与查询视频任务：API 参考
报错速查：按报错原文排查

更多细节

提交阶段报错原文

任务失败的 error.message 原文

本页目录