Image Generation API Documentation

KozeAI provides OpenAI-style image generation and editing interfaces. The image interface returns a uniform image response format, but the specific model-supported size, quality, reference image, and output format are determined by the channel adapter.

Authentication

All requests are authenticated via Authorization: Bearer . Used after creating an API token in the console.

export KOZEAI_API_KEY='sk-your-token'

export KOZEAI_BASE_URL='https://your-kozeai-domain'

API Overview

The image model can also be called via

/v1/chat/completions

. The chat interface will extract images from the text and messages and then convert them to the image interface format; it is recommended to use the dedicated image interface above when directly connecting.

1. 文生图

curl '$KOZEAI_BASE_URL/v1/images/generations' \

-H 'Authorization: Bearer $KOZEAI_API_KEY' \

-H 'Content-Type: application/json' \

-d '{

'model': 'gpt-image-1',

'prompt': 'An orange cat sitting by the window, cinematic light and shadow',

'n': 1,

'size': '1024x1024',

'quality': 'auto',

'response_format': 'url'

}

Request Parameters

Method	Path	Content-Type	Purpose
POST	/v1/images/generations	application/json	Text-generated Images

Parameters	Type	Required	Description
model	string	Is	Image model name. Actual available models are based on the returns from /v1/models.
prompt	string	Yes	Image content description. It is recommended to use a non-empty string.
n	integer	No	Number of elements generated, default 1, common validation range is 1-10.
size	string	No	Image size or aspect ratio, specific value is determined by the model.
quality	string	No	Quality level, common values are standard, hd, auto, 2k, 4k.
response_format	string	No	Common values are url or b64_json.
style	any	No	OpenAI compatible style parameter.
user / user_id	any	No	Caller user identifier.
extra_fields	object	No	Additional structured parameter; its effectiveness depends on the channel adapter.
background	any	No	Background settings.
moderation	any	No	Content moderation settings.
output_format	any	No	Output image format.
output_compression	integer	No	Output compression parameter, supported by some Codex image models.
partial_images	integer	No	Some image/streaming related parameters, supported by some Codex image models.
watermark	boolean	No	Watermark switch, its effectiveness depends on the channel.
watermark_enabled	any	No	Compatible with some upstream watermark parameters.
image	string/object/array	No	Refer to image URL, data URL, or image object; some channels will automatically enter the editing process.

DALL·E Size and Defaults

dall-e-3

Model	size Allowed Values	Defaults
dall-e-2 / dall-e	256x256、512x512、1024x1024	1024x1024
1024x1024、1024x1792、1792x1024	1024x1024
gpt-image-1 / gpt-image-2	Determined by upstream model	quality=auto

size Must use half-width letters x, do not use multiplication signs ×.

2. Image Editing

Standard editing requests use the multipart form, with the image field named image. Multiple input images can be reused using image or image[].

curl '$KOZEAI_BASE_URL/v1/images/edits' \
-H 'Authorization: Bearer $KOZEAI_API_KEY' \
-F 'model=gpt-image-1' \
-F 'prompt=Change the background to night scene and retain subject details' \
-F 'image=@./input.png' \
-F 'n=1' \
-F 'quality=standard'

Common Form Fields:

Field	Type	Description
model	string	Image editing model.
prompt	string	Editing requirements.
image / image[]	file	Input an image, at least one.
mask	file	Mask image; primarily used for OpenAI/Codex compatible editing workflows.
n	integer	Number of elements generated, default 1, range 1-10.
size	string	Output size or ratio.
quality	string	Output quality.
response_format	string	url or b64_json, depending on the channel.
watermark	boolean	Watermark switch, depending on the channel.

Some channels also support JSON edit requests, such as setting image to a data URL or image URL; however, OpenAI, Codex, and ChatGPT OAuth edit paths preferentially use multipart.

3. Channel Differences

Channel	Additional Behaviors
OpenAI / DALL·E	Forwarded by OpenAI image field; DALL·E has strict validation for size.
xAI	size will be converted to aspect_ratio and resolution; response_format defaults to b64_json. Additional JSON parameters such as aspect_ratio and resolution are supported.
Flow	size Supports aspect ratios of 1:1, 16:9, 9:16, 4:3, and 3:4; quality=2k/4k triggers a scaling process. Reference images are uploaded via image.
Jimeng / Dreamina	size is used for aspect ratio mapping; quality=hd will select a higher resolution; the reference image will enter the blend process.
Codex	Additionally supports input_fidelity, mask, stream, output_format, output_compression, partial_images.
ChatGPT OAuth	Actually consumes model, prompt, n and edits images; other image parameters may be ignored.
Grok	response_format Only supports url or b64_json, default is url; editing requests require at least one image.

Parameters not defined in public fields are not automatically guaranteed to be passed through. Only additional parameters explicitly read by the corresponding channel adapter will take effect.

4. Response Format

{

"created": 1751000000,

"data": [
{
"url": "https://example.com/generated.png",

"b64_json": "",

"revised_prompt": "An orange cat sitting by the window, cinematic light and shadow"

}
]

}

When `response_format=b64_json`, the image content is located in `data[].b64_json`; when using URL format, the image address is located in `data[].url`. Different channels may return empty strings for unused fields.

5. JavaScript call example

const baseURL = process.env.KOZEAI_BASE_URL;
const apiKey = process.env.KOZEAI_API_KEY;

const response = await fetch(`${baseURL}/v1/images/generations`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-1',
    prompt: 'A minimal product illustration on a white background',
    n: 1, size: 1024x1024,

response_format: url,

}),

});

if (!response.ok) {

throw new Error(await response.text());

}
const result = await response.json();

console.log(result.data[0].url || result.data[0].b64_json);

6. Common Errors

• model is required：Model name not passed.
• prompt is required：Prompt word is empty.
• n must be between 1 and 10：Generation quantity exceeds public limit.
• size must be one of ...：DALL·E uses an unsupported size.
• image is required: The edit interface did not upload an image or provided a recognizable image reference.
• unsupported ... response_format: The target channel does not support the requested output format.