核心 API

图片 API

图片请求使用独立的 Images 端点。KHaiXAPI 当前支持 OpenAI gpt-image-2，可完成图片生成、编辑和异步任务。

端点与模型

用途	最终 endpoint	可用模型
生成	`POST https://api.khaix.net/v1/images/generations`	`gpt-image-2`
编辑	`POST https://api.khaix.net/v1/images/edits`	`gpt-image-2`
认证	`Authorization: Bearer $KHAIX_API_KEY`	使用同一网关密钥

SDK 的 Base URL 填写 https://api.khaix.net/v1；直接发送 HTTP 请求时使用上表完整地址。不要把 gpt-image-2 放入文字模型 endpoint。

图片生成

使用 JSON 发送提示词。尺寸决定图片档位，n 决定生成数量；图片结果通常位于 data[].b64_json 或 data[].url，具体输出格式以响应为准。

cURL · gpt-image-2

curl https://api.khaix.net/v1/images/generations \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "为一款精密工业传感器生成电商主图：银色金属外壳，浅灰无缝背景，正面三分之四视角，柔和棚拍光，产品完整居中，不要品牌标志、可读文字和水印",
    "size": "1024x1024",
    "quality": "high",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

常用字段还包括 response_format、moderation、style、output_compression 与流式图片字段。若不传 model，Sub2API 当前默认图片模型为 gpt-image-2。

图片编辑

编辑请求可使用 JSON 图片 URL（包括 data:image/...;base64,...）或 multipart 文件上传。JSON 编辑使用 images[].image_url，可选 mask.image_url；当前实现不使用 OpenAI Files 的 file_id。

cURL · JSON edit

curl https://api.khaix.net/v1/images/edits \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "将产品图背景替换为浅灰无缝摄影棚背景，保留传感器的金属材质、边缘和自然阴影，不添加品牌标志、可读文字或水印",
    "images": [
      {"image_url": "data:image/png;base64,BASE64_DATA"}
    ],
    "mask": {
      "image_url": "data:image/png;base64,MASK_BASE64_DATA"
    },
    "size": "1024x1024",
    "n": 1
  }'

cURL · multipart

curl https://api.khaix.net/v1/images/edits \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=将产品图背景替换为浅灰无缝摄影棚背景，保留传感器的金属材质、边缘和自然阴影，不添加品牌标志、可读文字或水印" \
  -F "image=@sensor.png" \
  -F "mask=@sensor-mask.png" \
  -F "size=1024x1024"

异步任务

需要异步处理时，可使用 /v1/images/generations/async 或 /v1/images/edits/async，然后用 GET /v1/images/tasks/{task_id} 查询状态。异步任务依赖 Sub2API 的对象存储配置，未启用对象存储时应使用同步端点；轮询仍使用同一 API Key。

操作	地址	说明
创建生成任务	`POST /v1/images/generations/async`	返回任务 ID
创建编辑任务	`POST /v1/images/edits/async`	支持图片和 mask
查询任务	`GET /v1/images/tasks/{task_id}`	返回状态与结果

流式字段 stream 与异步任务不是同一机制；需要任务轮询时不要同时依赖流式响应。

图片计费

图片不套用文字模型的单一 Token 公式。常见维度是生成数量 n、尺寸档位和质量；编辑还可能产生图片输入 Token。最终价格、倍率、分组权限和是否允许生图以控制台当前配置为准。

模型	计费维度	配置提示
`gpt-image-2`	1K / 2K / 4K 图片输出；编辑可能含图片输入 Token	在渠道或分组中填写 image input / output 价格

不要把文档中的示例价格当作实时上游价格；管理员应在 Sub2API 控制台维护当前渠道价格，用户侧以实际调用记录为准。

常见错误

400：模型不适用：gpt-image-2 不能放在 /v1/chat/completions 或文字 Responses 示例中，请改用 Images 端点。
403：未允许生图：检查密钥所属分组是否启用 allow_image_generation，以及该分组是否配置 OpenAI 图片渠道。
413：请求体过大：压缩或缩小 Base64 图片，或改用 multipart 文件上传。
空结果或 502：保留请求 ID、模型和 UTC 时间，检查上游图片渠道是否返回图像数据。
404：路径拼接错误：确认 Base URL 只填到 /v1，避免出现 /v1/v1/images。