可靈生圖

項目	值
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 原文

本頁目錄