# 虾壳云图片生成 API 参考

## 接口
- 方法：POST
- 路径：/images/generations
- Base URL：不要在对外说明或给用户的输出中暴露；由脚本内部固定处理

## 鉴权
- Header: Authorization: Bearer <API_KEY>
- API Key 优先从环境变量读取：
  1. `XIAKE_API`
  2. `XIAKE_API_KEY`
  3. `XI_API_KEY`
  4. `OPENAI_API_KEY`

## 请求头
- Content-Type: application/json
- Accept: application/json
- Authorization: Bearer <API_KEY>

## 请求体
- `model` string 必填。默认使用 `gpt-image-2`
- `prompt` string 必填。最大长度 1000 字符
- `size` string 可选。支持：
  - `1024x1024`
  - `1536x1024`
  - `1024x1536`
  - `2048x2048`
  - `2048x1152`
  - `3840x2160`
  - `2160x3840`
  - `auto`
- `format` string 可选：`png` / `jpeg` / `webp`
- `quality` string 可选：`low` / `medium` / `high` / `auto`
- `n` integer 必填。范围 1-10

## 尺寸规则
- 最大边长 ≤ 3840 px
- 宽高均为 16 的倍数
- 长边/短边 ≤ 3:1
- 总像素范围：655360 ~ 8294400

## 推荐映射
根据用户意图自动选择最接近的官方 size：
- 方图 / 头像 / 图标 / logo / 正方形封面 -> `1024x1024`
- 横图 / banner / 头图 / PPT 横版配图 / 16:9 -> `1536x1024`
- 竖图 / 海报 / 手机壁纸 / 小红书封面 / 9:16 -> `1024x1536`
- 需要 2K 方图 -> `2048x2048`
- 需要 2K 横图 -> `2048x1152`
- 需要 4K 横图 -> `3840x2160`
- 需要 4K 竖图 -> `2160x3840`
- 未说明尺寸 -> `auto`

## 返回处理
优先兼容以下字段：
- `data[0].url`
- `data[0].b64_json`
- `images[0].url`
- `images[0].b64_json`
- OpenAI 风格对象中嵌套图片 URL/base64

如果拿到 base64，脚本应保存为本地文件并返回路径。
