# 翎航生图 API 接入规范

更新：2026-09-09。与本站生图工作台实现对齐。
网页：https://api.tianjinlinghang.com/docs/image/
工作台：https://api.tianjinlinghang.com/m/image-studio/
示例：https://api.tianjinlinghang.com/docs/image/image-client-20260909.py

## 鉴权与模型选择

- API Base URL：`https://api.tianjinlinghang.com/v1`。
- 请求头：`Authorization: Bearer sk-YOUR_SITE_TOKEN`。
- 使用客户自己创建的站内令牌，不使用上游密钥、管理员 Cookie 或 New-Api-User。
- GPT 使用「生图专用分组」；Gemini 使用「gemni视频-生图」；Grok 使用「grok生图」。
- 不输出、上传、公开存储或导出真实令牌。返回图片 URL 不得携带本站 Authorization。
- 请求 `GET /v1/models` 获取当前令牌可用模型。响应：`{"data":[{"id":"gpt-image-2"}]}`。
- 插件模型下拉使用 `data[].id` 去重排序。可按 `/image|dall-e|flux|imagen|seedream|ideogram|banana/i` 筛选生图候选，排除 `/video|veo|omni/i`；不同厂商仍需独立协议适配。
- 切换接口或令牌，清空模型列表、旧模型选择和用户图片，再重新拉取；请求失败显示 HTTP 错误。
- `model` 必须原样使用列表中返回的 ID。不要自动拼接分辨率或比例到模型名。
- 旧文档的 `gpt-image-2k-16x9` 等命名不是当前通用规则，只有列表确实返回该 ID 时才可使用。
- 模型列表不生成图片，但不保证上游实时健康或一定支持所有编辑功能。

## GPT 文生图

`POST https://api.tianjinlinghang.com/v1/images/generations`

Content-Type: application/json

```json
{
  "model": "gpt-image-2",
  "prompt": "白色背景上的青绿色几何建筑",
  "size": "1536x1024",
  "quality": "auto",
  "output_format": "png",
  "moderation": "auto",
  "n": 1,
  "response_format": "b64_json"
}
```

## GPT 图生图

`POST https://api.tianjinlinghang.com/v1/images/edits`

Content-Type: multipart/form-data，boundary 由客户端自动生成。

- 文本字段：`model`、`prompt`、`size`、`quality=auto`、`output_format=png`、`moderation=auto`、`n=1`、`response_format=b64_json`。
- 文件字段：重复 `image[]`，上传真实文件字节。单张也支持 `image`，不要混用。
- 不要使用 JSON 的 `reference` 字段，也不要把本地路径当作图片内容。
- 不要手动填写 Content-Type，否则可能丢失 multipart boundary。
- 工作台与示例客户端参考图上限：最多9张；PNG/JPEG/WebP；单张10MB、原图合计100MB，单张3200万像素。插件同步将上传选择、计数校验与提交校验改为9张、合计100MB，单张10MB不变；下载示例校验文件类型和字节上限，不解码像素尺寸。
- 单张10MB与9张上限同时生效，所以实际原图最多约90MB。100MB按原始文件字节计算（代码为100×1024×1024），不是Base64长度；Gemini的Base64传输体积约增加三分之一。上游或代理可能有更低请求上限，HTTP 413时请压缩或减少参考图，不能自动拆单或重试。
- 9张是客户端上限，不代表所有上游型号都支持9张。GPT Image 与 Gemini 3 生图模型可按多图协议提交；旧版模型、自定义别名或上游另有更低限制时，以实际能力为准。不得静默截断参考图或拆成多次生成。

PowerShell 示例：

```powershell
curl.exe 'https://api.tianjinlinghang.com/v1/images/edits' `
  --max-time 600 --retry 0 --fail-with-body `
  -H "Authorization: Bearer $env:LINGHANG_API_KEY" `
  --form-string 'model=gpt-image-2' `
  --form-string 'prompt=保留主体，改为白色背景' `
  --form-string 'size=1536x1024' `
  --form-string 'quality=auto' `
  --form-string 'output_format=png' `
  --form-string 'moderation=auto' `
  --form-string 'n=1' `
  --form-string 'response_format=b64_json' `
  -F 'image[]=@reference.png;type=image/png' `
  -o result.json
```

第二张至第九张参考图依次追加 `-F 'image[]=@reference-2.jpg;type=image/jpeg'` 等文件字段，全部放在同一次请求中；不是把 `n` 改为9。

## 尺寸与型号

- GPT Image 2：`size` 取 `auto` 或 `WIDTHxHEIGHT`；宽高必须为16倍数；每边≤3840；比例1:3至3:1；像素总数655360至8294400；高于2560x1440为实验性。
- GPT Image 1 / 1.5：`auto`、`1024x1024`、`1536x1024`、`1024x1536`。
- `gpt-image-2-1k`、`gpt-image-2-2k`、`gpt-image-2-4k` 等是上游别名，使用准确列表值，不自动替换为另一型号。工作台按后缀限制像素预算1K≤1572864、2K≤4194304、4K≤8294400；这是保守限制，不是官方别名保证。
- 不要在插件固定旧版价格，使用站内现行模型价格与分组计费规则。不能保证所有模型「成功出图才扣费」。

## Gemini / Nano Banana

当前原生 Gemini 生图不使用 Images API。

`POST https://api.tianjinlinghang.com/v1beta/models/{model}:generateContent`

用 URL 编码后的真实模型 ID 替换 `{model}`，如 `gemini-3.1-flash-image` 或 `nano-banana-2`，须在当前令牌列表内。
若客户端 Base URL 已含 `/v1`，替换末尾 `/v1` 为 `/v1beta`，不要拼成 `/v1/v1beta`。
鉴权仍为 Bearer 客户令牌，Content-Type: application/json。

```json
{
  "contents": [{"role": "user", "parts": [
    {"text": "保留主体，将背景改为白色摄影棚"},
    {"inlineData": {"mimeType": "image/png", "data": "REFERENCE_BASE64"}}
  ]}],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
  }
}
```

- 文生图移除 inlineData，只保留 text；图生图为每张参考图追加 inlineData，客户端最多9张，同一次请求包含全部参考图。模型能力边界同上。
- Base64 不带 data URL 前缀，mimeType 与真实文件一致。
- 3.1 Flash Image / nano-banana-2：比例1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:4、4:1、1:8、8:1；imageSize 为512、1K、2K、4K。
- Pro：上述前10种比例，1K/2K/4K。旧版/Lite不要发送512或4K覆盖值；工作台使用默认分辨率。
- 自动时省略 aspectRatio/imageSize，不传字符串auto；不要发送GPT专用size/quality/output_format。

## Grok 当前边界

`POST /v1/images/generations`，JSON 仅包含：

```json
{"model":"grok-imagine-image","prompt":"青绿色几何建筑","n":1,"response_format":"b64_json"}
```

站内当前xAI适配器不转发参考图、尺寸、质量。不要宣称Grok图生图已支持；如果上传参考图应阻止提交，不能静默忽略参考图。

## 解析响应

- GPT/Grok：`data[].b64_json`；若只有 `data[].url`，单独处理安全HTTPS下载，不携带API Key，不自动访问内网或任意重定向。
- Gemini：检查 error、promptFeedback.blockReason、candidates[].finishReason；读取 content.parts[].inlineData 或 inline_data 的 data、mimeType/mime_type，排除 thought:true。thoughtSignature 不等于 thought:true。
- 只接收PNG/JPEG/WebP，按实际类型保存扩展名；不能将所有返回都标成PNG。
- Gemini的HTTPS fileData.fileUri可给用户手动打开；仅文本或空图必须显示明确提示，不能当作成功。
- 不打印原始Base64或令牌；错误保留HTTP状态和 X-Oneapi-Request-Id。
- 429/502/524/超时/无图不自动重试，不盲目改端点再提交。生成可能已进入上游，应先核对日志和扣费。
- UI使用提交锁；每次用户确认只发起一条生成POST。NewAPI内部可能重试，不等于客户端应再重试。

## 客户端示例

下载同目录 image-client-20260909.py，安装 requests，将站内令牌设置到 LINGHANG_API_KEY。

```text
python image-client-20260909.py models
python image-client-20260909.py generate --model gpt-image-2 --prompt "青绿色几何建筑" --size 1536x1024
python image-client-20260909.py edit --model gpt-image-2 --prompt "保留主体，改为白色背景" --reference reference.png --size 1536x1024
python image-client-20260909.py edit --model gemini-3.1-flash-image --prompt "保留主体，改为白色背景" --reference reference.png --aspect-ratio 16:9 --resolution 1K
```

models只读；generate/edit会真实请求并可能扣费。示例不自动重试、不下载URL-only响应，输出文件以随机名称保存，不覆盖已有图片。

## 给 Codex / 插件开发者

生图插件的模型下拉与Codex主对话模型选择器是不同功能。请实现GET /v1/models、GPT multipart图生图、Gemini原生图生图、分模型参数校验、图片解析与无重复提交。不要只依靠旧版清晰度下拉自动拼模型名。
网页和纯文本规范更新不会自动升级已安装插件。先使用模拟响应验证插件，未获客户确认不要执行可能扣费的真实生成。

参考：https://developers.openai.com/api/docs/guides/image-generation
参考：https://developers.openai.com/api/reference/resources/images/methods/edit
参考：https://ai.google.dev/gemini-api/docs/image-generation