图片生成 API

本文档描述图片生成相关接口协议。

对应能力：

图片生成（文生图）
图片编辑（图生图）
图片任务查询
图片任务列表

1. 基础信息

API 基础地址：https://router.qingting.work
接口前缀：/v1/images

2. 鉴权方式

支持两种写法：

http

Authorization: Bearer <api_key>

或：

http

x-api-key: <api_key>

认证失败时返回：

json

{
  "error": {
    "message": "Invalid gateway API key",
    "type": "authentication_error"
  }
}

3. 计费说明

3.1 计费模式

图片生成按次计费，每次调用收取固定费用，与生成图片数量无关。具体价格由模型配置的 imagePrice 决定。

3.2 计费时机

同步模式：

调用生成接口，上游直接返回图片结果
系统立即完成扣费

异步模式：

调用生成接口（async: true），系统冻结预估费用
轮询查询接口获取任务状态
任务成功完成时，系统解冻并完成实际扣费
任务失败或取消时，系统解冻预扣金额，不扣费

3.3 余额保护

提交请求前系统检查可用余额（钱包余额 - 已冻结金额）
异步模式下，任务创建时冻结预估费用，防止并发超额消费
冻结金额在任务终态（成功/失败/取消）时自动释放

4. 路由清单

路由	方法	说明
`/v1/images/generations`	`POST`	生成图片（文生图）
`/v1/images/edits`	`POST`	编辑图片（图生图）
`/v1/images/tasks`	`GET`	查询图片任务列表
`/v1/images/{task_id}`	`GET`	查询图片任务详情

5. 生成图片

5.1 请求

http

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

请求体：

json

{
  "model": "gpt-image-1",
  "prompt": "一只在草地上奔跑的金毛犬，阳光明媚",
  "size": "1024x1024",
  "quality": "auto",
  "n": 1
}

参数说明：

参数	类型	必填	说明
`model`	string	是	模型名称，请在「模型广场」查看可用模型
`prompt`	string	是	图片描述提示词
`size`	string	否	图片尺寸，如 `1024x1024`、`1024x1536`、`1536x1024` 等
`quality`	string	否	图片质量，枚举值：`low`、`medium`、`high`、`auto`，默认 `auto`
`n`	integer	否	生成图片数量，默认 1
`response_format`	string	否	返回格式，`url`（默认）或 `b64_json`

代码示例：

import requests

api_key = "your-api-key"
base_url = "https://router.qingting.work"

response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-1",
        "prompt": "一只在草地上奔跑的金毛犬，阳光明媚",
        "size": "1024x1024",
        "quality": "auto",
        "n": 1,
    },
)

data = response.json()

# 异步模式
if "task_id" in data:
    print("Task ID:", data["task_id"])
    print("Status:", data["status"])

# 同步模式
elif "data" in data:
    for img in data["data"]:
        print("Image URL:", img["url"])

5.2 同步响应

上游直接返回结果时：

json

{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ],
  "usage": {
    "total_tokens": 1200
  }
}

5.3 异步响应

上游返回任务 ID 时：

json

{
  "task_id": "img-2026xxxx",
  "status": "queued"
}

5.4 错误响应

json

{
  "error": {
    "message": "账户可用余额不足",
    "type": "insufficient_wallet_balance"
  }
}

6. 编辑图片

6.1 请求

http

POST /v1/images/edits
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

参数说明：

参数	类型	必填	说明
`model`	string	是	模型名称
`prompt`	string	是	编辑描述提示词
`image[]`	file	是	参考图片文件，支持多张（多次传入 `image[]` 字段）
`size`	string	否	输出图片尺寸
`quality`	string	否	图片质量，枚举值：`low`、`medium`、`high`、`auto`，默认 `auto`
`n`	integer	否	生成图片数量，默认 1

单张图片示例：

bash

curl -X POST "https://router.qingting.work/v1/images/edits" \
  -H "Authorization: Bearer your-api-key" \
  -F 'image[]=@"./source-image.png"' \
  -F 'prompt="将背景替换为星空"' \
  -F 'model="gpt-image-1"' \
  -F 'size="1024x1024"'

多张图片示例：

bash

curl -X POST "https://router.qingting.work/v1/images/edits" \
  -H "Authorization: Bearer your-api-key" \
  -F 'image[]=@"./image-1.png"' \
  -F 'image[]=@"./image-2.png"' \
  -F 'prompt="将这两张图片融合"' \
  -F 'model="gpt-image-1"'

代码示例：

import requests

api_key = "your-api-key"
base_url = "https://router.qingting.work"

response = requests.post(
    f"{base_url}/v1/images/edits",
    headers={"Authorization": f"Bearer {api_key}"},
    files=[
        ("image[]", ("source.png", open("./source-image.png", "rb"), "image/png")),
    ],
    data={
        "model": "gpt-image-1",
        "prompt": "将背景替换为星空",
        "size": "1024x1024",
    },
)

data = response.json()
print("Task ID:", data.get("task_id"))

响应格式与生成接口一致。

7. 查询图片任务

7.1 请求

http

GET /v1/images/{task_id}
Authorization: Bearer your-api-key

代码示例：

import requests
import time

api_key = "your-api-key"
base_url = "https://router.qingting.work"
task_id = "img-2026xxxx"

while True:
    response = requests.get(
        f"{base_url}/v1/images/{task_id}",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    data = response.json()
    status = data.get("status", "")

    if status in ("succeeded", "completed"):
        images = data.get("data", [])
        for img in images:
            print("Image URL:", img["url"])
        break
    elif status in ("failed", "cancelled"):
        print("Task failed:", data.get("error", {}).get("message", ""))
        break
    else:
        print(f"Status: {status}, waiting...")
        time.sleep(5)

7.2 成功响应示例

json

{
  "status": "succeeded",
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ],
  "usage": {
    "total_tokens": 1200
  }
}

7.3 处理中响应示例

json

{
  "status": "processing",
  "task_id": "img-2026xxxx"
}

7.4 轮询建议

创建任务后每 5 秒查询一次
status 为 succeeded 或 completed 时读取 data 中的图片 URL
status 为 failed / cancelled 时按失败处理
图片 URL 有时效性，建议及时下载保存

8. 查询图片任务列表

8.1 请求

http

GET /v1/images/tasks?limit=50
Authorization: Bearer your-api-key

参数说明：

参数	类型	必填	说明
`limit`	integer	否	返回数量上限，默认 50，最大 100

8.2 成功响应示例

json

{
  "data": [
    {
      "id": "img-2026xxxx",
      "status": "succeeded",
      "model": "gpt-image-1",
      "prompt": "一只在草地上奔跑的金毛犬",
      "imageUrls": ["https://example.com/generated-image.png"],
      "error": null,
      "createdAt": "2026-04-23T10:30:00.000Z",
      "completedAt": "2026-04-23T10:30:15.000Z"
    }
  ]
}

9. 推荐接入流程

9.1 异步模式（推荐）

POST /v1/images/generations（async: true）创建任务
从响应中获取 task_id
每 5 秒轮询 GET /v1/images/{task_id}
status 为 succeeded 时读取图片 URL

9.2 同步模式

POST /v1/images/generations（不传 async 或 async: false）
等待响应，直接从 data 中获取图片 URL
注意：同步模式下请求可能耗时较长，建议设置合理的超时时间

9.3 图片编辑

准备参考图片文件
POST /v1/images/edits 以 multipart/form-data 提交编辑请求，支持多张图片
轮询获取结果，流程同异步生成

10. 错误处理

HTTP 状态码	说明
400	请求参数错误（缺少必填字段、格式不正确等）
401	认证失败：API Key 无效、已过期或未提供
402	余额不足或 API Key 可用余额已耗尽
404	未找到支持图片生成的模型或供应商
503	供应商 API Key 未配置或供应商不可用