图像 API

品牌：包菜大王
入口：https://api.713812.xyz

本文描述客户侧可用的调用方式。协议以 OpenAI Images 兼容 为主；文末补充 Gemini 多模态形态，便于高级集成。

1. 接口总览

能力	方法	路径	说明
查询模型	GET	/v1/models	列出 Key 可见模型
文生图	POST	/v1/images/generations	OpenAI Images 兼容（主推）
图片编辑	POST	/v1/images/edits	参考图 / 编辑（视上游支持）
对话出图	POST	/v1/chat/completions	部分客户端用 Chat 拿 Markdown 图链
Gemini 文生图 / 多模态	POST	/v1beta/models/{model}:generateContent	多图垫图更自然

鉴权失败时返回 401。路径不存在才会 404——图像 generations 已在网关暴露。

2. 鉴权

任选一种（推荐 Bearer）：

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

Gemini 风格亦可：

x-goog-api-key: YOUR_API_KEY

Key 由包菜大王控制台发放，可绑定分组与额度。勿把 Key 写进前端公开仓库。

3. 查询模型

GET /v1/models
Authorization: Bearer YOUR_API_KEY

常见图像模型（以控制台开通为准）

模型 ID	定位
gpt-image-2	通用文生图，OpenAI SDK 友好
gpt-image-2.5	更高质量档
gpt-image-1k-1x1 / 2k-1x1 / 4k-*	名称锁定分辨率与画幅
gemini-3-pro-image	高质量多模态
gemini-3.1-flash-image	更快 / 更省
flux-2 / flux-2-pro	Flux 系列
nano-banana-pro-1k-1x1 等	固定规格出图

客户一般使用短名即可；网关会按开通名单映射到实际上游模型。

4. 文生图 · /v1/images/generations

请求

POST /v1/images/generations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

参数表

字段	类型	必填	说明
model	string	是	如 gpt-image-2
prompt	string	是	文本描述；过长可能被上游截断
size	string	否	如 1024x1024；固定规格模型可省略
quality	string	否	如 low / medium / high（视模型）
n	int	否	生成数量，默认 1；建议保持 1 以降延迟
response_format	string	否	url（推荐）或 b64_json

最小示例

{
  "model": "gpt-image-2",
  "prompt": "日系便利店夜景，霓虹，胶片颗粒",
  "size": "1024x1024",
  "response_format": "url"
}

成功响应（示意）

{
  "created": 1710000000,
  "data": [
    {
      "url": "https://api.713812.xyz/generated/example.png"
    }
  ]
}

b64_json 模式下为 Base64 字段而非 URL。生成图 URL 请在有效期内下载存档。

5. 分辨率与画幅

通用 size（OpenAI 风格）

常用：1024x1024、1024x1792、1792x1024 等（以模型实际支持为准）。

名称即规格（推荐批量业务）

使用已编码模型，避免 size 歧义：

• nano-banana-pro-{1k|2k|4k}-{1x1|16x9|9x16|4x3|3x4}
• nano-banana2.1-{1k|2k|4k}-{1x1|16x9|...}（新版，相对 pro 溢价）
• gpt-image-{1k|2k|4k}-...

像素对照（近似，以实际上游为准）：

比例	1K	2K	4K
1:1	1024²	2048²	4096²
16:9	~1360×768	~2752×1536	~5504×3072
9:16	对调上列	对调	对调

6. 图片编辑 · /v1/images/edits

用于参考图引导或编辑类需求。

JSON 形态（URL 参考图）

{
  "model": "gpt-image-2",
  "prompt": "保留主体，背景换成浅灰影棚",
  "image": "https://example.com/source.jpg",
  "size": "1024x1024",
  "quality": "high"
}

multipart 形态（本地文件）

与 OpenAI 类似：字段 image（文件）、prompt、model；若支持 mask，可附加 mask。
具体是否接受 multipart 以联调为准；若 415/400，改用 JSON + 公网 URL 或 Gemini inlineData。

7. 响应格式小结

协议	成功时图片位置
Images	data[].url 或 data[].b64_json
Chat Completions	choices[].message.content 内 Markdown 图片链
Gemini	candidates[].content.parts[].inlineData 或 fileData.fileUri

可选投递方式（上游支持时）：Header x-image-delivery: uri 倾向返回 URL，减轻 Base64 带宽。

8. 代码示例

见 快速开始（curl / Python / Node）。
SDK 只需修改：

base_url = https://api.713812.xyz/v1
api_key  = YOUR_API_KEY

9. 常见错误

见 错误码与限流。摘要：401 查 Key；400 查参数；408/429 退避；内容安全类勿死磕重试。

10. 超时、重试与并发

• 客户端超时：1K/2K ≥ 120s，4K ≥ 180–300s。
• 对 408/429/5xx 指数退避，最多 3 次。
• 推荐并发与 RPM 见错误文档（按套餐分级）。

11. 用量与计费

额度与单价以包菜大王 控制台 / 订单为准。套餐说明见 定价。

12. 安全

• Key 仅放服务端；轮换泄露 Key。
• 不要提交违法、侵权、侵害他人肖像权的生成需求。
• 日志可能保留 prompt 与元数据；勿在 prompt 中塞入隐私证件号等。
• 遵守当地生成式 AI 与广告法规范。

13. 验收清单

• [ ] 使用客户 Key 可 GET /v1/models 看到约定图像模型
• [ ] POST /v1/images/generations 成功返回 URL/b64
• [ ] 错误 Key → 401；非法模型 → 4xx
• [ ] 超时设置符合错误文档建议
• [ ] 并发未超过套餐建议值

14. 与其他接口的区别

项目	图像 API（本文）	对话文本 API	视频渠道
主路径	/v1/images/*	/v1/chat/completions（文本模型）	独立视频模型列表
计费	按张 / 按规格	按 token	按时长规格
延迟	数秒～数十秒	通常更快	更长

同一 Base URL 下靠 model 名称 与 Key 权限 区分能力。图像套餐默认不含视频能力。

附录 · Gemini 多模态要点

1. 接口 — POST /v1beta/models/{model}:generateContent
2. 鉴权 — Bearer / x-goog-api-key
3. 模型 — gemini-3-pro-image 等
4. 文生图 — contents.parts[].text + generationConfig.imageConfig
5. 画幅 — aspectRatio、imageSize（1K/2K/4K）
6. 垫图 — parts 可混合 text + inlineData；多图语义由 prompt 约定
7. 响应 — candidates[].content.parts[].inlineData 或 fileUri

完整 curl 示例见 快速开始 §4。

---

文档版本：包菜大王 image pack · 维护：包菜大王 API