生成图片缓存与下载 API 文档
认证方式: Authorization: Bearer {your_api_key}（网关令牌）
基础地址:https://your-domain.com（你的 new-api 网关地址）
Content-Type:application/json
最后更新: 2026-06-16
目录
1. 功能说明
| 特性 | 说明 |
|---|---|
| 自动存储 | 调用图片生成接口（/v1/images/generations、/v1/images/edits）时，返回的 base64 图片会异步存储到服务器 |
| 支持的上游 | Gemini Imagen 系列、OpenAI GPT Image 系列（所有以 b64_json 格式返回的图片） |
| 有效期 | 24 小时，过期后自动删除文件和数据库记录 |
| 关联方式 | 通过 request_id 关联到日志记录，可从日志页面跳转查看 |
| 权限隔离 | 用户只能查看和下载自己生成的图片 |
| 对原有接口无影响 | 图片生成的 API 响应格式不变，仍然返回 base64 数据 |
注意：仅当上游返回 b64_json格式的图片时才会存储。如果响应中使用url格式返回，则不会缓存。
2. 接口总览
| 接口 | 方法 | 说明 |
|---|---|---|
/api/generated-images/ | GET | 查询生成图片列表（支持分页和按 request_id 筛选） |
/api/generated-images/:id/file | GET | 下载指定图片文件 |
Authorization: Bearer {token}）。3. 查询生成图片列表
接口
GET /api/generated-images/请求头
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
request_id | string | 否 | 按请求 ID 筛选，返回该次请求生成的所有图片。与日志记录中的 request_id 对应 |
page | integer | 否 | 页码，默认 1（仅在不指定 request_id 时生效） |
page_size | integer | 否 | 每页数量，默认 20，最大 100（仅在不指定 request_id 时生效） |
响应示例
按 request_id 查询
GET /api/generated-images/?request_id=req-abc123def456{
"success": true,
"data": [
{
"id": 42,
"user_id": 1,
"request_id": "req-abc123def456",
"filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
"mime_type": "image/png",
"model": "gpt-image-2",
"prompt": "一只可爱的橘猫坐在窗台上看夕阳",
"image_index": 0,
"file_size": 1048576,
"created_at": 1750089600,
"expires_at": 1750176000
}
]
}分页查询
GET /api/generated-images/?page=1&page_size=10{
"success": true,
"data": [
{
"id": 42,
"user_id": 1,
"request_id": "req-abc123def456",
"filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
"mime_type": "image/png",
"model": "gpt-image-2",
"prompt": "一只可爱的橘猫坐在窗台上看夕阳",
"image_index": 0,
"file_size": 1048576,
"created_at": 1750089600,
"expires_at": 1750176000
}
],
"total": 56,
"page": 1,
"page_size": 10
}4. 下载生成图片文件
接口
GET /api/generated-images/:id/file路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 图片记录 ID（从列表接口获取） |
请求头
成功响应
200 OKimage/png）private, max-age=3600错误响应
| HTTP 状态码 | 场景 | 响应体 |
|---|---|---|
400 | 图片 ID 格式无效 | {"success": false, "message": "invalid image id"} |
404 | 图片不存在或非当前用户所有 | {"success": false, "message": "image not found"} |
410 | 图片已过期（超过 24 小时） | {"success": false, "message": "image has expired"} |
5. 数据结构
GeneratedImage 对象
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 图片记录唯一 ID |
user_id | integer | 所属用户 ID |
request_id | string | 关联的 API 请求 ID，与日志中的 request_id 一致 |
filename | string | 服务器存储的文件名（UUID 格式） |
mime_type | string | 图片 MIME 类型，如 image/png、image/jpeg、image/webp |
model | string | 生成图片使用的模型名称 |
prompt | string | 生成时的提示词（如可获取） |
image_index | integer | 同一请求中的图片序号（从 0 开始，当 n > 1 时用于区分多张图片） |
file_size | integer | 文件大小（字节） |
created_at | integer | 创建时间（Unix 时间戳，秒） |
expires_at | integer | 过期时间（Unix 时间戳，秒），过期后自动删除 |
6. 错误处理
通用错误格式
{
"success": false,
"message": "错误描述"
}错误码汇总
| HTTP 状态码 | 错误场景 | 说明 |
|---|---|---|
400 | 参数错误 | 图片 ID 格式不正确 |
401 | 认证失败 | API Key 无效或已过期 |
403 | 权限拒绝 | 路径校验未通过 |
404 | 图片不存在 | 图片记录不存在或不属于当前用户 |
410 | 图片已过期 | 图片已超过 24 小时有效期，已被自动清理 |
500 | 服务器错误 | 内部错误，请稍后重试 |
7. 使用场景与示例
场景一：从日志页面查看生成的图片
request_id 调用接口获取关联图片：场景二：Python 批量下载图片
场景三：curl 下载单张图片
场景四：分页浏览所有历史生成图片
修改于 2026-06-16 12:06:15