Kling Image

Generate and expand images with Kling asynchronously: parameters, responses, and caveats.

Item	Value
Base URL	`https://api.hop-base.com/v1`
Submit an image task	`POST /v1/images/generations`
Poll a task	`GET /v1/video/tasks/{task_id}`
Group	Kling Official

Every Kling image model runs as an asynchronous task: submission returns 202 with a task id, you poll the query endpoint, and a finished task lists image URLs in outputs[].

Available models

Model	Model ID	`quality` tiers	Reference images	Official price
Kling Image 3.0	`kling-image-v3`	1k / 2k	0–1	$0.0294/ image
Kling Image 3.0 Omni	`kling-image-v3-omni`	1k / 2k / 4k	0–10	$0.0294from/ image
Kling Image O1	`kling-image-o1`	1k / 2k / 4k	0–10	$0.0294from/ image
Kling Image 2.1 (text-to-image)	`kling-image-v2-1`	1k / 2k	None	$0.0147/ image
Kling Image 2.1 (image-to-image)	`kling-image-v2-1-i2i`	1k / 2k	Exactly 1	$0.0294/ image
Kling Image 2.1 (multi-reference)	`kling-image-v2-1-multi-ref`	1k / 2k	2–4	$0.0588from/ image
Kling Image Expand	`kling-image-expand`	1k	Exactly 1	$0.0294/ image

Choosing: use 2.1 (text-to-image) for plain text prompts, 3.0 Omni or O1 for 4k or many reference images, and Image Expand to extend an existing image outward.

Request parameters

Parameter	Required	Type and limits	Default	Description
`model`	Required	string	—	An image model ID from the table above
`prompt`	Required without images	string	—	Send it, a non-empty `images`, or both
`quality`	Optional	`1k` / `2k` / `4k`	`1k`	Quality tier; allowed values vary by model
`n`	Optional	integer 1–9	`1`	Number of images
`images`	Per model	array of `url` / `file_id` items	—	Reference images, or the image to expand
`extra`	Expansion only	object with the four expansion ratios	—	See Image expansion

Only these fields are accepted; others such as size, aspect_ratio, or response_format return 400.
A video model ID in model returns 400.
quality is case-insensitive; OpenAI values such as high or standard are rejected.
n is billed per output image.
A non-empty extra on any other image model returns 400.

Reference images

Each images[] item carries exactly one of url or file_id, and no usage:

{
  "model": "kling-image-v3-omni",
  "prompt": "Place the cups from both images on one wooden table",
  "quality": "2k",
  "images": [
    { "url": "https://cdn.example.com/cup-a.png" },
    { "file_id": "your-file-id" }
  ]
}

url must be an absolute, publicly reachable http:// or https:// URL.
Empty strings, relative paths, non-HTTP(S) schemes such as file://, private or loopback addresses, and URLs with credentials are rejected synchronously.
A file_id must be a Kling asset available to your key, not a Seedance asset ID.
The number of reference images is limited per model; see Available models.

Image expansion

kling-image-expand extends one image outward; the ratios go in 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
  }
}

Each of the 4 ratios is a number from 0–2; an omitted ratio is 0.
The four ratios cannot all be 0.
The expanded area may not exceed 3× the original: (1+left+right) × (1+up+down) ≤ 3.

Response

A successful submit returns HTTP 202 with the task ID in the top-level id, shaped like kt57x<task-id>:

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

Poll GET /v1/video/tasks/{task_id} with that id. A finished task looks like this:

{
  "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 }
}

Field	Type	Description
`id`	string	HopBase task ID, the same at submit and poll
`object`	string	`image.generation.task` on submit, `video.generation.task` on poll
`status`	string	`queued` → `processing` → `completed` or `failed`
`progress`	integer	Progress percentage; poll only
`requested_images`	integer	Number of images requested; submit only
`billing_bucket`	string	Billing tier for the quality; submit only
`outputs`	string[]	Image URLs; only when `completed`
`usage.billed_images`	integer	Images billed, equal to the images produced
`error.code` / `error.message`	string	Only when `failed`; see Failed tasks

Only completed and failed are terminal, so treat any other value as still running.

Once the task finishes, the query's top-level usage also carries cost — the amount actually deducted from your balance for this task, 0 for an uncharged failure — and the currency.

Examples

Submit a text-to-image task, poll until it ends, then download the first image:

# 1. Submit
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-v3",
    "prompt": "A ceramic teapot on a sunlit wooden table",
    "quality": "1k",
    "n": 1
  }'

# 2. Poll with the returned id until status is completed or failed
curl https://api.hop-base.com/v1/video/tasks/ktYOUR_TASK_ID \
  -H "Authorization: Bearer sk-your-key"

Caveats

Image URLs are served from api.hop-base.com and stay valid for 6 hours from task completion, so download them promptly.
Querying again returns the same URL without extending it, and an expired link returns 410.
A task still unfinished 2 hours after creation is marked failed and not billed, and tasks cannot be cancelled.
Kling image generation reserves no balance and is only blocked once your balance is at or below zero.
Before sending paid work, confirm the exact model IDs your key returns with GET /v1/models.

Common errors

A submission error creates no task and bills nothing; error.message explains the cause:

Error	Fix
`request body does not match the JSON contract: json: unknown field "size"`	Remove the extra field; set the tier with `quality`
`prompt and input images cannot both be empty`	Add a `prompt` or reference images
`images[0] must provide exactly one of url or file_id`	Keep only `url` or `file_id` in each item
`images[0].url must be a publicly accessible absolute http(s) URL`	Use a public HTTP(S) URL
`model "kling-image-v3" does not support quality tier "4k"`	Pick a tier the model supports
`model "kling-image-v2-1-multi-ref" requires 2 to 4 input images`	Match the model's reference image count
`model "<model ID>" is not an image model in this catalog`	Check the ID with `GET /v1/models` (404)

Each line starting with # is the trigger and the next line is the verbatim error.message:

# A field outside the table
request body does not match the JSON contract: json: unknown field "<field>"

# Both prompt and images are empty
prompt and input images cannot both be empty

# An images[] item with neither or both of url / file_id
images[<index>] must provide exactly one of url or file_id

# url that is not a public absolute http(s) address
images[<index>].url must be a publicly accessible absolute http(s) URL

# usage on an images[] item
images[<index>].usage is not part of the image generation API; remove this field

# A quality tier the model does not offer
model "<model ID>" does not support quality tier "<value>"

# n outside 1–9
n must be between 1 and 9, got <value>

# More reference images than the model allows
model "<model ID>" accepts at most <max> input images, got <count>

# Images sent to 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 without exactly 1 image
model "kling-image-v2-1-i2i" requires exactly 1 input image

# kling-image-v2-1-multi-ref without 2–4 images
model "kling-image-v2-1-multi-ref" requires 2 to 4 input images

# extra on a non-expansion model
model "<model ID>" does not accept unverified extra parameters

# Expansion without exactly 1 image
image expansion requires exactly 1 input image

# Expansion extra with a key other than the four ratios
extra.<key> is not a verified parameter of the image expansion API

# Expansion ratio that is not a number from 0 to 2
extra.<key> must be a number between 0 and 2

# All four ratios are 0
the four expansion ratios cannot all be 0

# Expanded area over 3x the original
expanded area cannot exceed 3x the original image

# Image model ID not in the catalog (404)
model "<model ID>" is not an image model in this catalog

Failed tasks

A failed task still answers the query with HTTP 200 and status failed. Branch on the stable code in error.code and show the error explanation to your user. Older failed tasks may have no code.

Case	`error.code`
Prompt or reference image refused by moderation	`input_sensitive`
Output blocked by moderation	`safety_rejected`
Concurrency ceiling reached	`rate_limited`
Model version retired	`unsupported_model`
Prompt too long, or parameters or media rejected	`invalid_request`
Reference image unreadable	`reference_input_invalid`
Generation failed or stopped before finishing	`generation_failed`
Still unfinished 2 hours after creation	`timeout`
Task ended with no output	`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

Kling images are billed per output image, at the rate for the model and quality tier; failed tasks and polling are never billed. Each model's price is on its model card linked above, and your own rate is the one shown in the signed-in model catalog.

Next steps

Image API: overview of every image series
GPT Image, Gemini image, Seedream, Grok Imagine image: other image series
Kling video: Kling video, motion control, avatar, and lip sync
Create image and Get video task: API reference
Troubleshooting: look up an error message

More details

Submission error messages

Failed-task error.message values

On this page