KToken Docs

Appearance

Images Api ​

接口用途 ​

OpenAI Images API 兼容入口，用于图片生成和图片编辑。

图片生成和图片编辑都支持同步返回，也支持异步任务模式。异步模式适合处理耗时较长、客户端不想一直等待连接返回的场景。

请求路径 ​

text
POST /v1/images/generations
POST /v1/images/edits

也可以使用更短的路径：

text
POST /images/generations
POST /images/edits

认证方式 ​

任选一种即可：

  • Authorization: Bearer <API_KEY>
  • x-api-key: <API_KEY>

适用场景 ​

  • 图片生成：POST /images/generations 或 POST /v1/images/generations
  • 图片编辑：POST /images/edits 或 POST /v1/images/edits
  • 异步图片生成：POST /images/generations 或 POST /v1/images/generations，并传入异步开关
  • 异步图片编辑：POST /images/edits 或 POST /v1/images/edits，并传入异步开关
  • 异步任务查询：GET /gpt/images/:task_id

官方 API 参考 ​

支持说明 ​

  • 支持 JSON 与 multipart 图片请求
  • 支持常见 OpenAI Images API 参数
  • API Key 需要具备 OpenAI 图片能力
  • 图片生成和图片编辑都可以使用异步任务模式

参数说明 ​

常用字段 ​

参数类型必填说明
modelstring通常是图片模型
promptstring生成时通常是图片生成提示词
imagefile编辑时通常是原始图片文件
maskfile否蒙版文件
sizestring否尺寸
streamboolean否是否启用流式

完整字段请参考 OpenAI 官方规范。

使用限制 ​

字段 / 行为说明
API Key 能力API Key 必须支持 OpenAI 图片能力
图片生成权限当前账号或套餐必须允许图片生成
multipart图片编辑等上传文件场景可使用 multipart 请求
空图片结果如果服务没有拿到有效图片结果，会返回错误
异步模式图片生成和图片编辑都可通过请求头或请求体切换为异步任务
异步模型限制异步图片任务要求模型名以 gpt-image- 开头
stream=true + 异步异步模式不支持 stream=true
stream=true + 同步不传异步开关时，可以按普通同步链路使用流式

同步返回 ​

默认情况下，接口会直接返回标准 OpenAI Images JSON 响应。

示例响应 ​

json
{
  "created": 1747470000,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

异步图片模式 ​

异步模式会先返回一个任务 ID，客户端再用这个任务 ID 查询任务状态和图片结果。

触发方式 ​

以下两种方式任选其一：

方式一：请求头 ​

http
X-KToken-Async: true

推荐使用请求头方式，尤其是图片编辑这类 multipart/form-data 上传文件的请求。

方式二：请求体字段 ​

json
{
  "async": true
}

请求体字段方式适合 JSON 请求。multipart/form-data 请求请使用 X-KToken-Async: true。

适用接口 ​

  • POST /v1/images/generations
  • POST /images/generations
  • POST /v1/images/edits
  • POST /images/edits

异步返回示例 ​

提交成功后，接口不会直接返回图片结果，而是返回任务对象：

json
{
  "object": "task",
  "task_id": "f4b8b4f0b1c34d6a9e8f1029384756ab",
  "provider": "gpt",
  "capability": "image",
  "action": "generate",
  "status": "queued",
  "created": 1747470000
}

字段说明 ​

字段说明
object固定为 task
task_id异步任务 ID
provider服务类型，图片任务为 gpt
capability能力类型，图片任务为 image
action操作类型；图片生成是 generate，图片编辑是 edit
status初始状态通常为 queued
created任务创建时间戳

轮询接口 ​

使用返回中的 task_id 查询任务状态。推荐使用：

text
GET /gpt/images/:task_id

也支持：

text
GET /v1/gpt/images/:task_id

轮询接口同样需要 API Key，并且只能查询由同一个 API Key 创建的图片异步任务。

路径参数：

参数类型必填说明
task_idstring是异步任务 ID，来自图片异步提交响应

轮询响应字段 ​

字段说明
task_id任务 ID
request_id上游任务 ID；没有时会省略
status任务状态
created_at创建时间戳
started_at开始处理时间戳
finished_at完成时间戳
expires_at任务过期时间戳
url成功后返回的第一张图片 URL
download_url当前与 url 相同
error失败时返回，包含 code 与 message

常见状态包括：queued、running、succeeded、failed、expired、cancelled。

轮询响应示例 ​

排队或运行中：

json
{
  "task_id": "f4b8b4f0b1c34d6a9e8f1029384756ab",
  "request_id": "upstream_task_id",
  "status": "running",
  "created_at": 1747470000,
  "started_at": 1747470001,
  "expires_at": 1747473600
}

成功后：

json
{
  "task_id": "f4b8b4f0b1c34d6a9e8f1029384756ab",
  "request_id": "upstream_task_id",
  "status": "succeeded",
  "created_at": 1747470000,
  "started_at": 1747470001,
  "finished_at": 1747470020,
  "expires_at": 1747473600,
  "url": "https://example.com/generated-image.png",
  "download_url": "https://example.com/generated-image.png"
}

失败时：

json
{
  "task_id": "f4b8b4f0b1c34d6a9e8f1029384756ab",
  "status": "failed",
  "created_at": 1747470000,
  "finished_at": 1747470020,
  "error": {
    "code": "upstream_error",
    "message": "Image generation failed"
  }
}

常见状态包括：queued、running、succeeded、failed、expired、cancelled。

错误响应 ​

当前 API Key 不支持图片接口 ​

json
{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

没有图片生成权限 ​

json
{
  "error": {
    "type": "permission_error",
    "message": "Image generation is not allowed for this group"
  }
}

异步模式不支持流式 ​

json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Async mode does not support stream=true"
  }
}

异步模型不符合要求 ​

json
{
  "error": {
    "type": "invalid_request_error",
    "message": "k-token image generation requires an image model such as gpt-image-2"
  }
}

示例请求 ​

同步生成 ​

bash
curl https://api.nvue.dev/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴眼镜的橘猫坐在书桌前"
  }'

异步生成：请求头触发 ​

bash
curl https://api.nvue.dev/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "X-KToken-Async: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴眼镜的橘猫坐在书桌前"
  }'

异步生成：请求体触发 ​

bash
curl https://api.nvue.dev/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴眼镜的橘猫坐在书桌前",
    "async": true
  }'

异步编辑：请求头触发 ​

bash
curl https://api.nvue.dev/images/edits \
  -H "Authorization: Bearer sk-xxxx" \
  -H "X-KToken-Async: true" \
  -F model=gpt-image-2 \
  -F prompt="把背景改成夜晚的城市街道" \
  -F image=@input.png

同步流式请求 ​

不传异步开关时，请求会走普通图片链路，可以使用 stream=true。

bash
curl https://api.nvue.dev/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴眼镜的橘猫坐在书桌前",
    "stream": true
  }'

轮询异步任务 ​

bash
curl https://api.nvue.dev/gpt/images/f4b8b4f0b1c34d6a9e8f1029384756ab \
  -H "Authorization: Bearer sk-xxxx"

注意事项 ​

  • 图片接口不是所有 API Key 都可用；如果不确定，请先确认当前 API Key 是否支持 OpenAI 图片能力
  • 异步模式依赖图片异步任务能力；如果未开通，会按普通同步图片接口处理或返回相关错误
  • 异步提交响应不包含 poll_url 字段；请用返回的 task_id 拼接 /gpt/images/:task_id 轮询
  • 使用异步模式时，不要等待提交请求直接返回图片 URL，应轮询任务状态
  • 异步模式不能和 stream=true 同时使用；需要流式返回时，请不要传 X-KToken-Async: true 或 "async": true