DEVELOPER API

对话与图片生成 API

在工作台登录后，从账户栏的 API 入口创建密钥。对话请求不消耗积分；每个成功受理的图片生成请求消耗 1 积分，失败请求会自动返还。

鉴权

所有接口使用 Bearer API Key。完整密钥只会在创建时显示一次，请保存在你自己的密钥管理系统中。/v1/* 兼容接口支持浏览器跨域调用，使用 Bearer 密钥时不需要携带 Cookie。

Authorization: Bearer kmage_your_api_key

对话

POST /v1/chat/completions 返回 OpenAI 兼容的非流式对话响应，适合标题重组、卖点提炼和结构化文案任务。

KMAGE_BASE_URL="https://当前站点域名"
curl "$KMAGE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer kmage_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kmage-chat",
    "messages": [
      {"role": "system", "content": "只返回 JSON，不要 Markdown。"},
      {"role": "user", "content": "重组这个商品标题，并提炼核心卖点。"}
    ]
  }'

支持 system、user 和 assistant 文本消息，最后一条必须是 user。单次最多 40 条、合计 60000 个字符；当前不支持 stream: true。

文生图

POST /v1/images/generations（相对于当前站点域名）

KMAGE_BASE_URL="https://当前站点域名"
curl "$KMAGE_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer kmage_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "雨后的未来主义城市街道，霓虹倒影，电影感",
    "model": "gpt-image-2.5-sunburst",
    "size": "1024x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

OpenAI 图像编辑兼容接口

POST /v1/images/edits 兼容 OpenAI 常用的 multipart/form-data 编辑请求，字段名使用 image、prompt 和可选的 mask。

KMAGE_BASE_URL="https://当前站点域名"
curl "$KMAGE_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer kmage_your_api_key" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "prompt=保留人物主体，将背景改为雪山" \
  -F "image=@source.png" \
  -F "mask=@mask.png"

也支持新版 JSON 图片引用：images 中传入 image_url 为 Base64 Data URL 的图片对象。当前单次编辑生成 1 张图片；mask 的透明区域作为可编辑区域提示。

curl "$KMAGE_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer kmage_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "把背景改成雪山",
    "images": [{"image_url": "data:image/png;base64,iVBORw0KGgo..."}],
    "response_format": "b64_json"
  }'

图生图

图生图使用同一个 POST /v1/images/generations 接口。在 JSON 中通过 reference_images 传入最多 10 张 Base64 Data URL 格式的参考图；单图请求仍可使用 reference_image。

KMAGE_BASE_URL="https://当前站点域名"
curl "$KMAGE_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer kmage_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "保留人物主体，将背景改为雪山，电影感光影",
	    "reference_images": [
	      "data:image/png;base64,iVBORw0KGgo...",
	      "data:image/webp;base64,UklGRiIAAABXRUJQVlA..."
	    ],
    "model": "gpt-image-2.5-sunburst",
    "size": "1024x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

参考图支持 PNG、JPG 和 WebP，最多 10 张，每张解码后最大 10MB。reference_image 与 reference_images 不能同时使用。这个扩展接口仅接受 JSON；需要兼容 OpenAI 标准编辑请求时，请使用上面的 /v1/images/edits。

获取模型

GET /v1/models 与 GET /v1/models/{model} 使用相同的 Bearer API Key，返回 OpenAI 兼容的模型对象。

请求字段

prompt：文生图时必填，服务不设置应用层字符数上限；仍受请求体大小和上游模型上下文限制。图生图时可省略，省略后使用默认的参考图创作指令。
reference_image：单张图生图兼容字段，格式必须为 data:image/png;base64,...、data:image/jpeg;base64,... 或 data:image/webp;base64,...；解码后最大 10MB。
reference_images：多图融合字段，传入 1–10 个与 reference_image 相同格式的 Data URL，每张解码后最大 10MB。
model：可选，默认 gpt-image-2.5-sunburst；当前可用模型：gpt-image-2 gpt-image-2.5-flare gpt-image-2.5-sunburst 。
size：可选，支持自定义整数比例格式 宽:高（例如 4:5、21:9），也支持自定义像素尺寸 宽x高（例如 1072x1456，单边最大 4096）；指定像素尺寸时，服务会在返回前居中裁剪并缩放到精确尺寸。另兼容 1024x1024（1:1）、1536x1024（3:2）、1024x1536（2:3）、1536x864（16:9）、864x1536（9:16）、1536x1152（4:3）、1152x1536（3:4）和 auto；默认 1024x1024。
quality：可选，auto、low、medium 或 high，并兼容 standard、hd，默认 auto。
n：可选，仅支持 1。
response_format：可选，支持 b64_json 或 url；省略时返回 Base64 图片，url 返回不会公开作品的 data URL。
OpenAI 客户端附带的 background、moderation、output_compression、output_format、style 和 user 兼容提示会被安全接收；最终图片格式与视觉效果仍由上游模型决定。

成功响应

data[0].b64_json 是不含 data URL 前缀的 Base64 图片内容；generation_time_ms 是实际生成耗时，不包含排队时间。

{
  "created": 1785200000,
  "generation_time_ms": 51023,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "revised_prompt": "..."
    }
  ]
}

错误响应

错误采用统一 JSON 格式。常见状态码包括 401（密钥无效）、402（积分不足）、429（生成并发或上游限流）及 5xx（服务暂不可用）。公开 /v1 接口不设置应用层每分钟请求数上限，但仍受当前生成并发和上游账号池容量约束。

{
  "error": {
    "message": "Insufficient credits to generate an image.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}