Skip to main content
POST
Submit an asynchronous request with model: "kling-v4-image" to POST /v1/images/generations. Read data[0].task_id, then query GET /v1/tasks/{task_id} for the result.

Authentication

string
required
Use Authorization: Bearer <token>, where <token> is your APIMart API key.

Request parameters

string
required
Must be kling-v4-image.
boolean
default:"false"
Whether to run content moderation before submitting the image task.
  • true: use omni-moderation-latest to review prompts and input images
  • false or omitted: do not send a moderation request, adding no moderation cost or latency (default)
string
required
Required for text-to-image, image-to-image, and series generation. Describe both desired and unwanted content here. Limits are 50,000 characters for English-only text and 21,000 for Chinese-only text and similar languages; mixed-language limits are proportional.
string[]
Up to 10 reference images, supplied as publicly accessible direct image URLs. For local files, use the image upload API first and pass the returned url.Supports JPG / JPEG / PNG / GIF. Each image must be at most 30 MB, at least 300 px in both width and height, and have an aspect ratio from 2:5 to 5:2.Reference images are checked at submission. A URL returning HTTP 403 / 404 / 410, either dimension below 300 px, a ratio outside 2:5–5:2, or an image larger than 30 MB returns HTTP 400 immediately, without creating a task or charging for generation. Other fetch failures, such as an origin timeout, are accepted initially; the task then fails and prepaid generation charges are fully refunded.Use @Image1, @Image2, and so on in the prompt to refer to images in array order. Images are still used as references without these markers.
integer
default:"1"
Number of outputs in standard mode: an integer from 1 to 9, default 1. In series mode, omit n or set it to 1; sequential_image_generation_options.max_images determines the output count. Passing n > 1 in series mode returns HTTP 400.
string
default:"2K"
Supports 2K (default), 4K, and 8K, case-insensitive, with PNG output. At 1:1, 2K is 2048×2048, 4K is 4096×4096, and 8K is 8192×8192; for other ratios, use the actual dimensions of the returned images.8K supports text-to-image, image-to-image, and series generation: 1–9 outputs in standard mode, 2–4 in series mode, and up to 10 reference images. Reference image formats, dimensions, and the 30 MB per-image limit remain unchanged.
string
default:"auto"
Output aspect ratio. Supports auto (default) and these 8 explicit ratios:16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9.auto chooses a ratio from the prompt or reference images. Pixel dimensions such as 2048x2048 are not supported.
string
Alias for size, with the same accepted values. If both are provided, aspect_ratio takes precedence.
string
default:"disabled"
Use disabled or omit this field for standard generation. Set it to auto to generate related images as a series; sequential_image_generation_options.max_images is then required. Here, auto does not choose the image count automatically.
object
Specifies the image count in series mode.
width, height, mask_url, pixel-based size, and watermark: true are not supported and return HTTP 400.

Request examples

Send these requests to POST /v1/images/generations. Replace example image URLs with accessible direct links.

Image-to-image

Generate three 4K images

Generate one 8K image

Set max_images to 2–4. In series mode, n may be omitted or set to 1, but cannot exceed 1. A series may take several minutes; keep the task_id and poll its status instead of submitting duplicate requests.

8K output and timing examples

These measurements are samples from the test environment. Dimensions, file sizes, and completion times are illustrative; actual results may vary. Poll every 5–10 seconds until completed or failed. estimated_time is fixed at 60 seconds and must not be used as an actual completion estimate or countdown. Keep the task_id and avoid resubmitting while waiting. 8K results are original PNG images, and a single file can exceed 100 MB. For lists and previews, use thumbnails you generate or load images on demand. Provide an original-file download option and indicate the large file size.

Query the task

Use the task query API and read data.status: pending / processing means the task is running, completed means success, and failed provides details in data.error.message.
The following illustrates a successful result. Image URLs are in data.result.images[].url[]; url is an array. Iterate through all outputs and download them promptly.

Billing

Charges depend on the actual image count and selected resolution tier. Reference images are charged separately per image. See the pricing page for current rates.
  • Standard generation with n=3 is billed for 3 outputs; series generation is billed for the actual returned count.
  • Each reference image is counted once per request, regardless of output count. For example, generating 3 images from 2 references incurs 2 input-image charges and 3 output-image charges.
  • Failed generation tasks are not charged; prepaid generation charges are fully refunded.

Common parameter errors

These parameter errors return HTTP 400 synchronously at submission, without creating a task or charging for generation. Read error.message for submission errors and data.error.message for failures after task creation.