图片生成 API 调用文档

KozeAI 提供 OpenAI 风格的图片生成和图片编辑接口。图片接口返回统一的图片响应格式，但具体模型支持的尺寸、质量、参考图和输出格式由渠道适配器决定。

鉴权

所有请求通过 Authorization: Bearer <API_TOKEN> 鉴权。在控制台创建 API 令牌后使用。

export KOZEAI_API_KEY="sk-your-token"
export KOZEAI_BASE_URL="https://your-kozeai-domain"

接口总览

方法	路径	Content-Type	用途
POST	/v1/images/generations	application/json	文生图
POST	/v1/images/edits	multipart/form-data	图片编辑/参考图生成

图片模型也可以通过 /v1/chat/completions 调用。聊天接口会提取文本和消息中的图片，再转换到图片接口格式；直接对接时建议使用上面的图片专用接口。

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": "一只坐在窗边的橘猫，电影感光影",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto",
    "response_format": "url"
  }'

请求参数

参数	类型	必填	说明
model	string	是	图片模型名称。实际可用模型以 /v1/models 返回为准。
prompt	string	是	图片内容描述。建议使用非空字符串。
n	integer	否	生成数量，默认 1，公共校验范围为 1-10。
size	string	否	图片尺寸或比例，具体取值由模型决定。
quality	string	否	质量档位，常见值为 standard、hd、auto、2k、4k。
response_format	string	否	常见值为 url 或 b64_json。
style	any	否	OpenAI 兼容风格参数。
user / user_id	any	否	调用方用户标识。
extra_fields	object	否	额外结构化参数；是否生效取决于渠道适配器。
background	any	否	背景设置。
moderation	any	否	内容审核设置。
output_format	any	否	输出图片格式。
output_compression	integer	否	输出压缩参数，部分 Codex 图片模型支持。
partial_images	integer	否	部分图片/流式相关参数，部分 Codex 图片模型支持。
watermark	boolean	否	水印开关，是否生效取决于渠道。
watermark_enabled	any	否	兼容部分上游的水印参数。
image	string/object/array	否	参考图片 URL、data URL 或图片对象；部分渠道会自动进入编辑流程。

DALL·E 尺寸和默认值

模型	size 允许值	默认值
dall-e-2 / dall-e	256x256、512x512、1024x1024	1024x1024
dall-e-3	1024x1024、1024x1792、1792x1024	1024x1024
gpt-image-1 / gpt-image-2	由上游模型决定	quality=auto

size 必须使用半角字母 x，不要使用乘号 ×。

2. 图片编辑

标准编辑请求使用 multipart 表单，图片字段名为 image。多个输入图片可以重复使用 image 或使用 image[]。

curl "$KOZEAI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=把背景改成夜景，并保留主体细节" \
  -F "image=@./input.png" \
  -F "n=1" \
  -F "quality=standard"

常用表单字段：

字段	类型	说明
model	string	图片编辑模型。
prompt	string	编辑要求。
image / image[]	file	输入图片，至少一张。
mask	file	遮罩图片；主要用于 OpenAI/Codex 兼容编辑流程。
n	integer	生成数量，默认 1，范围 1-10。
size	string	输出尺寸或比例。
quality	string	输出质量。
response_format	string	url 或 b64_json，取决于渠道。
watermark	boolean	水印开关，取决于渠道。

部分渠道还支持 JSON 编辑请求，例如将 image 设置为 data URL 或图片 URL；但 OpenAI、Codex、ChatGPT OAuth 编辑路径优先使用 multipart。

3. 渠道差异

渠道	额外行为
OpenAI / DALL·E	按 OpenAI 图片字段转发；DALL·E 对 size 有严格校验。
xAI	size 会转换为 aspect_ratio 和 resolution；response_format 默认 b64_json。支持 aspect_ratio、resolution 等额外 JSON 参数。
Flow	size 支持 1:1、16:9、9:16、4:3、3:4 等比例；quality=2k/4k 可触发放大流程。参考图通过 image 上传。
Jimeng / Dreamina	size 用于比例映射，quality=hd 会选择更高分辨率；参考图会进入 blend 流程。
Codex	额外支持 input_fidelity、mask、stream、output_format、output_compression、partial_images。
ChatGPT OAuth	实际消费 model、prompt、n 和编辑图片，其他图片参数可能被忽略。
Grok	response_format 仅支持 url 或 b64_json，默认 url；编辑请求需要至少一张图片。

未在公共字段中定义的参数不会自动保证透传。只有对应渠道适配器显式读取的额外参数才会生效。

4. 响应格式

{
  "created": 1751000000,
  "data": [
    {
      "url": "https://example.com/generated.png",
      "b64_json": "",
      "revised_prompt": "一只坐在窗边的橘猫，电影感光影"
    }
  ]
}

当 response_format=b64_json 时，图片内容位于 data[].b64_json；当使用 URL 格式时，图片地址位于 data[].url。不同渠道可能会将未使用的字段返回为空字符串。

5. JavaScript 调用示例

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. 常见错误

• model is required：未传模型名。
• prompt is required：提示词为空。
• n must be between 1 and 10：生成数量超出公共限制。
• size must be one of ...：DALL·E 使用了不支持的尺寸。
• image is required：编辑接口未上传图片或未提供可识别的图片引用。
• unsupported ... response_format：目标渠道不支持请求的输出格式。