KToken Docs

Appearance

POST /v1/images/generations 与 POST /v1/images/edits ​

接口用途 ​

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

除了常规同步返回外，当启用 k_token 扩展时，这组接口还支持异步任务模式。

请求路径 ​

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 /images/edits
  • GET /v1/gpt/images/:task_id
  • GET /gpt/images/:task_id

适用平台 ​

  • 仅 OpenAI 平台支持

如果当前分组不是 OpenAI，代码会直接返回不支持。

上游官方规范 ​

本项目支持说明 ​

  • 支持 JSON 与 multipart 图片请求
  • 会解析图片请求能力类型
  • 会做图片能力权限检查
  • 会做用户并发与图片并发控制
  • 当启用 k_token 扩展时，支持异步图片任务模式

参数说明 ​

常用上游标准字段 ​

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

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

KToken 差异与限制 ​

字段 / 行为说明
平台限制非 OpenAI 平台直接返回 404 not_found_error
分组权限即使是 OpenAI 分组，也必须允许图片生成
multipartContent-Type 为 multipart 时，运维上下文记录方式不同，但业务语义不变
空响应如果上游返回空图片结果，代码会返回 500 Image response is empty
异步模式当 k_token 扩展启用时，可通过请求头或请求体切换为异步任务
stream=true + 异步异步模式下明确不支持 stream=true，会返回 400

同步返回 ​

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

示例响应 ​

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

异步图片模式 ​

如果部署启用了 k_token 扩展，图片接口支持异步提交。

触发方式 ​

以下两种方式任选其一：

方式一：请求头 ​

http
X-KToken-Async: true

方式二：请求体字段 ​

json
{
  "async": true
}

服务端会在内部移除 async 字段，再按正常图片请求继续处理。

适用接口 ​

  • POST /v1/images/generations
  • POST /v1/images/edits
  • 以及它们的根路径别名

异步返回示例 ​

命中异步模式后，接口不会直接返回图片结果，而是返回任务对象：

json
{
  "object": "task",
  "task_id": "kt_123456",
  "provider": "gpt",
  "capability": "image",
  "action": "generate",
  "status": "queued",
  "poll_url": "/v1/gpt/images/kt_123456",
  "created": 1747470000
}

字段说明 ​

字段说明
object固定为 task
task_id异步任务 ID
provider当前实现里为 gpt
capability当前实现里为 image
action当前实现里为 generate
status初始状态通常为 queued
poll_url用于轮询任务状态的路径
created任务创建时间戳

轮询接口 ​

使用返回中的 poll_url 轮询任务：

text
GET /v1/gpt/images/:task_id

也可以走根路径别名：

text
GET /gpt/images/:task_id

当前对外接入时，推荐优先使用修复后的轮询路径：

text
GET /gpt/images/:task_id

错误响应 ​

非 OpenAI 平台 ​

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

示例请求 ​

同步生成 ​

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

异步生成：请求头触发 ​

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

异步生成：请求体触发 ​

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

轮询异步任务 ​

bash
curl https://your-domain/api/v1/gpt/images/kt_123456 \
  -H "Authorization: Bearer sk-xxxx"

注意事项 ​

  • 图片接口不是跨平台统一能力
  • 如果客户端不确定当前分组平台，请先不要默认调用图片接口
  • 异步模式依赖 k_token 扩展；未启用扩展时，仍按普通同步图片接口处理
  • 如果你使用异步模式，应该改为轮询 /gpt/images/:task_id，而不是等待当前请求直接返回图片 URL