DEVELOPER API

图片生成 API

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

鉴权

所有接口使用 Bearer API Key。完整密钥只会在创建时显示一次，请保存在你自己的密钥管理系统中。

Authorization: Bearer kmage_your_api_key

生成图片

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",
    "size": "1024x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

获取模型

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

请求字段

prompt：必填，图片描述，最多 2000 个字符。
model：可选，默认 gpt-image-2。
size：可选，1024x1024、1536x1024、1024x1536 或 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（服务暂不可用）。

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