Skip to content

API.md

Latest commit

 

History

History
208 lines (163 loc) · 5.29 KB

API.md

File metadata and controls

208 lines (163 loc) · 5.29 KB
Raw

Chat-Image 图像生成 API 文档

Base URL http://localhost:56780 鉴权 无需前端传递，由服务端 config.js 统一注入

1. 文生图

POST /api/images/generate

将提示词发给后端模型生成图片，服务端保存图片后返回可直接访问的 URL。

请求头

Content-Type: application/json

请求体

{
  "prompt":  "a cute cartoon cat sitting on a cloud, flat design",
  "model":   "gpt-image-2",
  "size":    "1920x1080",
  "quality": "medium",
  "n":       1
}
字段 类型 必填 默认值 说明
prompt string ✅ — 图片描述文本
model string ❌ gpt-image-2 生图模型
size string ❌ 1920x1080 期望尺寸或比例（1920x1080/1024x1024/16:9/1:1 等），后端自动映射为 gpt-image-2 支持的尺寸
quality string ❌ hd standard(1K档) / medium(2K档·中画质) / hd(2K档·高画质)
n number ❌ 1 生成数量（仅保留最大分辨率那张）

实际向上游发出的尺寸需满足 gpt-image-2 约束（宽高均 16 整除，最高 2K）。后端按 size+quality 映射到：1:1→1024x1024/2048x2048，16:9→1536x1024/2048x1152，9:16→1024x1536/1152x2048，4:3→1024x768/2048x1536，3:4→768x1024/1536x2048，21:9→1536x640/2048x880。

成功响应 200

{
  "created": 1741524463,
  "data": [
    { "url": "/images/20260309_210743_363/original/image_0.png" }
  ]
}

2. Chat 生图（多轮对话）

POST /api/generate

以 OpenAI Chat Completions 格式发送，支持多轮上下文，图片 URL 内嵌于 content 字段返回。

请求头

Content-Type: application/json

请求体

{
  "model": "gemini-3.1-flash-image",
  "messages": [
    { "role": "user", "content": "画一只坐在云上的猫" }
  ]
}
字段 类型 必填 说明
model string ✅ 模型名
messages array ✅ 消息数组，格式同 OpenAI Chat API
messages[].role string ✅ user / assistant / system
messages[].content string | array ✅ 文本字符串，或 [{type:"text", text:"..."}]

成功响应 200

{
  "id": "xxx",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "/images/20260309_210548_780/original/image_0.png"
      }
    }
  ]
}

3. 图生图（图片编辑）

POST /api/images/edit

上传参考图 + 提示词，生成编辑后的图片。

请求头

Content-Type: application/json

请求体

{
  "prompt":      "将背景换成海边夕阳",
  "imageBase64": "<base64编码的图片数据，不含 data:image/...;base64, 前缀>",
  "mimeType":    "image/png",
  "model":       "gpt-image-2",
  "quality":     "medium",
  "aspectRatio": "16-9"
}
字段 类型 必填 默认值 说明
prompt string ✅ — 编辑描述
imageBase64 string ✅ — 参考图片的 Base64 数据
mimeType string ❌ image/png 图片 MIME 类型
model string ❌ gpt-image-2 模型名
quality string ❌ medium standard(1K) / medium(2K中) / hd(2K高)
aspectRatio string ❌ 16-9 1-1 / 16-9 / 9-16 / 4-3 / 3-4 / 21-9

后端自动将 imageBase64 转为 multipart/form-data 调上游 /v1/images/edits，并按 aspect+quality 映射到 16 整除的实际尺寸（同上）。

成功响应 200

{
  "data": [
    { "url": "/images/20260309_xxxxxx_xxx/original/image_0.png" }
  ]
}

4. 图片访问

GET /images/:timestamp/:quality/:filename

参数 说明
timestamp 生成时的时间戳目录名，如 20260309_210743_363
quality original / preview（1920px） / thumbnail（200px）
filename 固定为 image_0.png 
GET /images/20260309_210743_363/original/image_0.png   → 原图
GET /images/20260309_210743_363/preview/image_0.png    → 预览图
GET /images/20260309_210743_363/thumbnail/image_0.png  → 缩略图

5. 公共配置

GET /api/config

获取服务端当前配置的前端默认值（用于初始化页面）。

响应 200

{
  "defaultApiKey":   "sk-xxx",
  "defaultApiBase":  "http://localhost:56780",
  "enhanceApiBase":  "http://localhost:8317/v1",
  "enhanceApiKey":   "sk-xxx",
  "enhanceApiModel": "gemini-3-flash"
}

6. 历史记录

GET /api/history

返回所有历史生成记录，按时间倒序排列。

响应 200

[
  {
    "folderName":  "20260309_210743_363",
    "timestamp":   "2026-03-09T13:07:43.363Z",
    "prompt":      "a cute cartoon cat",
    "imageCount":  1,
    "thumbnailUrls": ["/images/20260309_210743_363/thumbnail/image_0.png"],
    "parameters":  { "model": "gpt-image-2", "size": "1024x1024" }
  }
]

通用错误格式

HTTP 场景 响应体
400 请求体格式错误 {"error": "无效的请求数据"}
429 触发限流 {"error": {"type": "rate_limit_error", "retry_after": 60}}
500 后端连接失败 {"error": "API请求失败: connect ECONNREFUSED"}