核心 API

图像生成 API

图片请求使用独立的 Images 端点。KHaiXAPI 图像服务面向 OpenAI GPT Image 系列，当前可用模型为 gpt-image-2，可完成图像生成、图片编辑，支持同步任务和异步任务。

端点与模型

用途	方法和地址	说明
查询模型	`GET https://api.khaix.net/v1/models`	返回当前可用模型
同步任务	`POST https://api.khaix.net/v1/images/generations`	等待生成完成后返回
图片编辑	`POST https://api.khaix.net/v1/images/edits`	使用参考图或 mask
异步任务	`POST https://api.khaix.net/v1/images/generations/async`	立即返回任务 ID
异步编辑	`POST https://api.khaix.net/v1/images/edits/async`	后台处理参考图和 mask
查询任务	`GET https://api.khaix.net/v1/images/tasks/{task_id}`	返回状态和最终结果

所有请求都使用 Authorization: Bearer $KHAIX_API_KEY。SDK 的 Base URL 填写 https://api.khaix.net/v1；直接发送 HTTP 请求时使用上表完整地址。图像生成模型必须显式填写 gpt-image-2，不要把它放入文本模型 endpoint，也不要依赖接口默认模型。

参数与尺寸规则

下表列出可使用的参数和接口返回行为。请求时请显式填写模型、尺寸和输出格式，并根据响应检查实际文件。

参数	可填写的值或范围	接口行为
`prompt`	必填，最长 32,000 字符	通过
`model`	`gpt-image-2`	必须显式填写 `gpt-image-2`
`size`	`auto` 或合法的 `WIDTHxHEIGHT`	部分尺寸会被归一化
`quality`	`low`、`medium`、`high`、`auto`	可使用 `low`、`medium`、`high`，结果中不会返回质量标签
`output_format`	`png`、`jpeg`、`webp`	建议使用 PNG；JPEG/WebP 请求会返回 PNG
`output_compression`	0-100，仅 JPEG/WebP 有效	暂不生效
`background`	`opaque` 或 `auto`	不支持 `transparent`
`moderation`	`auto` 或 `low`	支持 `auto` 和 `low`
`n`	1-10，默认值为 1	指定每次请求生成的图片数量；实际返回和计费按生成张数计算
`stream`	`false` 或 `true`	`true` 仅用于同步 SSE；异步任务必须使用 `false`
`partial_images`	0-3，仅 `stream:true` 有效	异步任务不能使用该参数
`user`	调用方定义的最终用户标识	用于标识最终用户
`response_format`	GPT Image 不支持	不要发送

尺寸规则与返回尺寸

尺寸使用像素值，不要传字符串形式的“1K”“2K”“4K”。宽高都必须是 16 的倍数，任一边不超过 3840，长宽比不超过 3:1，总像素应在 655,360 到 8,294,400 之间。

档位	请求尺寸	返回结果
1K	`1024x1024`	返回 1024x1024
2K 方图	`2048x2048`	返回 2048x2048
2K 横图	`2048x1152`	可能返回 2560x1440，不能依赖精确尺寸
4K 横图	`3840x2160`	返回 3840x2160，属于大尺寸请求

1K、2K 与 4K 档位

本站按图片最长边划分计费档位：最长边不超过 1024 为 1K，大于 1024 且不超过 2048 为 2K，大于 2048 为 4K。系统优先按实际输出尺寸判断；没有可识别的输出尺寸时使用请求尺寸，两者都无法识别时按 2K 处理。一次请求返回多张不同尺寸图片时，以其中最高档位作为本次请求的计费档位。

档位	最长边判定	常见方图（比例）	常见横图（比例）	常见竖图（比例）
1K	不超过 1024	`1024x1024`（1:1）	`1024x768`（4:3） `1024x640`（16:10）	`768x1024`（3:4） `640x1024`（10:16）
2K	大于 1024，不超过 2048	`1536x1536`（1:1） `2048x2048`（1:1）	`2048x1536`（4:3） `2048x1152`（16:9） `1536x1024`（3:2）	`1536x2048`（3:4） `1152x2048`（9:16） `1024x1536`（2:3）
4K	大于 2048	`2560x2560`（1:1） `2880x2880`（1:1）	`3840x2160`（16:9） `3072x2048`（3:2） `2560x1440`（16:9）	`2160x3840`（9:16） `2048x3072`（2:3） `1440x2560`（9:16）

上表尺寸均符合本页列出的 gpt-image-2 自定义尺寸范围，但最终应以接口实际返回尺寸为准。例如请求 2048x1152 后若实际输出为 2560x1440，最长边已超过 2048，因此按 4K 档位处理。

建议组合：1K 使用 1024x1024；2K 方图使用 2048x2048 和 quality=medium；4K 横图使用 3840x2160 和 quality=high。4K 属于大尺寸请求，请设置更长的同步超时或改用异步任务。

同步任务

同步端点会保持 HTTP 连接，直到图像生成完成。通常需要约 1~2 分钟，复杂请求可能更久。使用 JSON 发送提示词，并始终显式指定 model、size 和 output_format。

cURL

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
  }'

常用稳定字段是 prompt、size、quality、background、output_format、moderation 和 n。不要发送不适用于本模型的 response_format。

PowerShell 调用

PowerShell

$baseUrl = "https://api.khaix.net"
$headers = @{
    Authorization = "Bearer $env:KHAIX_API_KEY"
    "Content-Type" = "application/json"
}
$body = @{
    model = "gpt-image-2"
    prompt = "为一款精密工业传感器生成浅灰背景的专业产品图，不要 Logo、可读文字或水印"
    size = "1024x1024"
    quality = "medium"
    background = "opaque"
    output_format = "png"
    n = 1
} | ConvertTo-Json

$result = Invoke-RestMethod `
    -Uri "$baseUrl/v1/images/generations" `
    -Method Post -Headers $headers -Body $body -TimeoutSec 300

处理同步结果

同步响应通常使用 data[].url；部分兼容客户端可能返回 data[].b64_json。客户端应同时处理这两种字段，并按实际 Content-Type 保存文件。

PowerShell · url / b64_json

$item = $result.data[0]
if ($item.url) {
    Invoke-WebRequest -Uri $item.url -OutFile "generated-image.png"
} elseif ($item.b64_json) {
    [IO.File]::WriteAllBytes(
        "generated-image.png",
        [Convert]::FromBase64String($item.b64_json)
    )
} else {
    throw "Response contains neither url nor b64_json"
}

图片编辑

编辑请求可使用 JSON 图片 URL（包括 data:image/...;base64,...）或 multipart 文件上传。JSON 编辑使用 images[].image_url，可选 mask.image_url；此接口不支持 OpenAI Files 的 file_id。gpt-image-2 会以高保真方式处理输入图，请省略 input_fidelity 参数。

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"

异步任务

异步端点成功提交后立即返回 HTTP 202 和任务 ID，后台完成图片生成或编辑并上传对象存储，随后可通过任务接口查询结果。服务端必须启用并完整配置异步图片对象存储。创建和轮询必须使用同一 API Key。

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

创建生成任务

cURL · asynchronous generation

curl "https://api.khaix.net/v1/images/generations/async" \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "为一款精密工业传感器生成专业产品图，不要 Logo、可读文字或水印",
    "size": "2048x2048",
    "quality": "low",
    "background": "opaque",
    "output_format": "png",
    "moderation": "auto",
    "n": 1
  }'

创建编辑任务

异步编辑使用与同步编辑相同的 JSON 或 multipart 请求体，只需将端点改为 /v1/images/edits/async。下面是 JSON 参考图示例；multipart 上传时沿用前文的 image 和 mask 文件字段。

cURL · asynchronous edit

curl "https://api.khaix.net/v1/images/edits/async" \
  -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"}
    ],
    "size": "1024x1024",
    "n": 1
  }'

提交响应

请求校验通过并成功写入任务存储后，服务固定返回 HTTP 202。初始状态是 processing：

JSON · HTTP 202

{
  "id": "imgtask_0123456789abcdef",
  "task_id": "imgtask_0123456789abcdef",
  "object": "image.generation.task",
  "status": "processing",
  "created_at": 1784092800,
  "expires_at": 1784179200,
  "poll_url": "/v1/images/tasks/imgtask_0123456789abcdef"
}

成功提交固定包含 Cache-Control: no-store、相对轮询路径 Location 和 Retry-After: 3 响应头。异步请求不能带 "stream": true，否则会立即返回 HTTP 400。

轮询与下载

cURL · task polling

curl "https://api.khaix.net/v1/images/tasks/imgtask_0123456789abcdef" \
  -H "Authorization: Bearer $KHAIX_API_KEY"

已存在任务的轮询响应为 HTTP 200，应根据 JSON 的 status 判断。状态为 processing 时响应包含 Retry-After: 3；按照该值轮询，不要在客户端超时后直接重提任务，否则可能重复计费。

状态	含义	关键字段
`processing`	任务正在生成、编辑或上传对象存储	`created_at`、`expires_at`
`completed`	图片处理和对象存储上传均成功	`http_status`、`result`、`image_url`、`completed_at`
`failed`	上游请求、执行超时或对象存储转存失败	`http_status`、`error`、`completed_at`

当前接口没有取消端点，也不会返回 cancelled 或 expired 状态。任务最长执行 30 分钟；任务及其结果从最近一次状态更新起保留 24 小时。记录到期、任务 ID 不存在或使用了另一把 API Key 时，轮询返回 HTTP 404 image task not found。

完成与失败响应

JSON · completed

{
  "id": "imgtask_0123456789abcdef",
  "task_id": "imgtask_0123456789abcdef",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "image_url": "https://storage.example/image.png",
  "result": {
    "created": 1784092923,
    "data": [{"url": "https://storage.example/image.png"}]
  },
  "created_at": 1784092800,
  "completed_at": 1784092923,
  "expires_at": 1784179323
}

JSON · failed（轮询 HTTP 200）

{
  "id": "imgtask_0123456789abcdef",
  "task_id": "imgtask_0123456789abcdef",
  "object": "image.generation.task",
  "status": "failed",
  "http_status": 502,
  "error": {
    "type": "api_error",
    "message": "Upstream request failed"
  },
  "created_at": 1784092800,
  "completed_at": 1784092923,
  "expires_at": 1784179323
}

检查项	要求
任务状态	`status == completed`
结果状态	`http_status` 为 2xx，`result.data` 非空
文件下载	每个 `data[].url` 都能 GET，且响应是有效的 `image/*`
资源时效	未配置 `public_base_url` 时返回预签名临时 URL，有效期由存储配置决定，默认约 24 小时；配置后返回公开直链

无论返回临时地址还是公开直链，客户端都应及时下载并保存所需文件，不要把任务响应中的 URL 当作唯一永久副本。

图片计费

图片生成按实际生成张数计费，不按文本 Token、quality 或图片输入量单独计费。每张图片的单价根据本次请求最终确定的清晰度档位计算，分为 1K、2K 和 4K。n 可填写 1-10；一次请求返回多张图片时，按实际生成张数累计计费。各档位当前价格、倍率和可用分组以模型广场为准，当前密钥的图像生成权限请在控制台确认。

模型	计费方式	档位价格
`gpt-image-2`	每张生成图片分别计费；例如 `n=2` 且返回 2 张，则按 2 张计费	根据实际输出确定本次请求的 1K / 2K / 4K 档位，并以对应档位单价乘以实际生成张数

文档中的示例价格不代表实时价格；当前价格以模型广场为准，实际扣费以控制台调用记录为准。充值和付款使用人民币，1 CNY = 1 USD 消费额度；账户余额、模型价格与倍率、用量扣费和调用记录均以美元计价，人民币只用于充值金额、支付订单和付款记录。

常见错误

400：模型不适用：gpt-image-2 不能放在 /v1/chat/completions 或文本 Responses 示例中，请改用 Images 端点。
403：无图像生成权限：在控制台检查当前密钥的图像生成权限，并在模型广场确认可用模型和分组。
413：请求体过大：压缩或缩小 Base64 图片，或改用 multipart 文件上传。
空结果或 502：保留请求 ID、模型和 UTC 时间，检查图片服务是否返回图像数据。
404：异步任务未启用：出现 async image tasks are not enabled 时，服务端需要启用并完整配置异步图片对象存储。
404：任务不存在：确认轮询使用创建任务时的同一 API Key；未知、已过期或属于另一把 Key 的任务都返回 image task not found。
404：路径拼接错误：确保最终请求路径只包含一个 /v1，避免出现 /v1/v1/images。
格式或尺寸与请求不一致：以响应的 Content-Type、文件签名和实际宽高为准；JPEG/WebP 会返回 PNG，部分横向尺寸会被归一化。