Image Generation (Native / Upscale)

KuaiAPI has two image groups. The model names are the same; the group decides price, output behavior and C2PA.

Group	Best for	Price	C2PA
GPT-Image (Native)	Text-to-image, image-to-image, inpainting	0.15 per image (1K/2K/4K)	Yes
GPT-Image-Upscale (Upscale)	Image upscaling, generative upscale, reference-image redraw	1K 0.05 / 2K 0.08 / 4K 0.10	No

One key, one group

A native key only works with the native group; an upscale key only works with the upscale group. The model names are shared, but price, output behavior and C2PA differ.

01 Base URL

https://kuaiapi.net/v1

• Use the bare domain kuaiapi.net, not www (www redirects POST /v1/images/* with a 301, turning it into GET and failing).
• The URL already includes /v1; do not append another /v1.
• Send Authorization: Bearer sk-... on every request.

02 Models

Both groups currently expose these six image models:

Model	Notes
gpt-image-2.5-flare	Primary model, full quality tiers
gpt-image-2.5-sunburst	Second 2.5 line
gpt-image-2.6-flare	2.6 line, richer output formats
gpt-image-2.6-sunburst	Second 2.6 line
gpt-image-2.5	2.5 generic name
gpt-image-2	2nd-generation model

Use the list returned by GET /v1/models for your key. Requesting a model that is not in the group returns 404 / model not found.

03 Text-to-image: JSON

curl --fail-with-body --max-time 600 "https://kuaiapi.net/v1/images/generations" \
  -H "Authorization: Bearer $KUAiapi_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A small blue lighthouse on a white background",
    "size": "2048x2048",
    "quality": "medium",
    "n": 1,
    "response_format": "url"
  }'

Parameters

Parameter	Value	Notes
model	Full name from the group catalog	Do not add a quality suffix
prompt	Non-empty string	Describe the target image
size	1K / 2K / 4K, or pixel width/height	Pixels must be positive multiples of 16, separated by lowercase x
quality	low / medium / high; 2.5 also xhigh / max	Defaults to medium; higher tiers take longer
n	Positive integer; start with 1	Number of images
response_format	url / b64_json	Read data[].url / data[].b64_json

Common sizes:

Target	Value
Square 1K / 2K / 4K	1024x1024 / 2048x2048 / 4096x4096
Landscape / portrait	1536x1024 / 1024x1536
16:9 / 9:16	2048x1152 / 1152x2048

size=1K, 2K, 4K are also accepted and converted to pixels; for a 4K square use 4096x4096.

04 Image-to-image / inpainting: multipart

Use multipart/form-data for reference images and inpainting. Do not attach a reference image to the text-to-image endpoint.

curl --fail-with-body --max-time 600 "https://kuaiapi.net/v1/images/edits" \
  -H "Authorization: Bearer $KUAiapi_API_KEY" \
  --form-string 'model=gpt-image-2.5-flare' \
  --form-string 'prompt=Keep the subject and replace the background with light blue' \
  -F 'image=@reference.png' \
  --form-string 'size=2048x2048' \
  --form-string 'quality=medium' \
  --form-string 'n=1' \
  --form-string 'response_format=url'

• Single reference: image; multiple references: repeat image[], max 20 MB per file.
• Inpainting: add a mask file; transparent areas are repainted, opaque areas are kept.
• Both groups support this endpoint; the upscale group uses it for reference-image upscaling/redraw.

05 Reading the response

{
  "created": 1794209291,
  "data": [
    { "url": "https://..." }
  ]
}

• Iterate data[]; each element is one image. Do not scan the whole JSON for URLs.
• response_format=url → data[].url; response_format=b64_json → data[].b64_json (Base64 content, not a link).
• Image URLs are temporary (usually about 1 hour); download or re-host them immediately.
• The response may include revised_prompt, height, width; use the actual response.

06 Pricing and output

Group	1K	2K	4K	C2PA
GPT-Image (Native)	0.15/image	0.15/image	0.15/image	Yes
GPT-Image-Upscale (Upscale)	0.05/image	0.08/image	0.10/image	No

• Native output carries C2PA content credentials.
• Upscale is generative upscaling without C2PA; 4K 16:9 may extend the frame, so composition follows the actual output.
• Verified on-site: gpt-image-2.5-flare 2K text-to-image and reference-image both return 2048×2048 and bill 0.08 on the upscale group; native 1K returns 1024×1024 and bills 0.15.

07 Async and timeouts

Image calls are currently synchronous, with up to 600 seconds per request.

• A timeout means no result arrived in time, not that the job failed; do not retry concurrently.
• If async is enabled later, only HTTP 202 with a task_id counts as accepted; query with the same key and honor Retry-After.
• Without a task ID, keep x-request-id, time, model and a redacted request body for support.

08 Common errors

Error	Check first	Action
400 / Invalid image size	Positive multiples of 16; reference image original size	Use the sizes above; use multipart for edits
401 / 403 / 404	Key, bound group, model, full path	GET /v1/models; no duplicate /v1, no key from another site
429	Concurrency, rate, balance, key limits	Back off with Retry-After; do not retry the same job concurrently
502 / 503 / 504	Service capacity or auth	Keep x-request-id, time, model and a redacted request body
images/edits requires multipart/form-data	Edit endpoint Content-Type	Use multipart/form-data with the image field
Failed to validate API key	Key and group	Verify the key/group; contact support if it persists

Two most common traps

1. Do not use www: www.kuaiapi.net redirects POST /v1/images/* with a 301, turning it into GET and failing.
2. Do not append /v1 again: https://kuaiapi.net/v1 already includes /v1.