AI 生图 API 调用教程

直接交给 Codex 使用

适用于 Windows、CCS 驱动的 Codex 或 Codex 桌面端。保持当前 Codex 对话模型和主 API Key 不变；另建一把「生图专用分组」密钥，只让 Codex 在终端调用生图接口。

1. 下载给 Codex 的 MD 文档。
2. 在令牌管理创建「生图专用分组」令牌，把完整 sk-... 单独保存为 TXT；可先下载TXT 模板。
3. 把 MD、密钥 TXT 和生图要求一起发给 Codex。Codex 会下载专用客户端、只读检查模型，然后调用 Images API 并把图片保存到本机项目。

接口总览

API Base URL：https://api.tianjinlinghang.com/v1。所有请求使用客户令牌的 Authorization: Bearer sk-...，不需要管理员登录 Cookie。

1. 令牌与鉴权

1. 在令牌管理创建对应分组的令牌。GPT 使用「生图专用分组」；Gemini 使用「gemni视频-生图」；Grok 使用「grok生图」。分组名称以控制台为准。
2. 客户端保留且仅保留一个 sk- 前缀。插件使用客户自己的令牌，不能使用上游密钥或管理员会话。
3. 先请求 /v1/models 确认可用模型，再由用户明确提交生成任务。模型列表不生成图片，但不能证明每条上游实时可用。

下面 PowerShell 示例从本机环境变量 LINGHANG_API_KEY 读取令牌；不要把真实密钥写进插件源码、日志、导出配置或公开文档。

# 在本机设置 LINGHANG_API_KEY；勿把真实值提交到代码仓库。
$headers = @{ Authorization = "Bearer $env:LINGHANG_API_KEY" }

本站工作台与示例客户端最多上传 9 张参考图，每张不超过 10 MB，原图合计不超过 100 MB；PNG、JPEG、WebP，工作台单张不超过 3200 万像素。自建插件同步将选择、计数与提交上限改为 9 张、合计 100 MB，单张 10 MB 不变。这是客户端上限，不保证所有上游型号都支持 9 张；GPT Image 与 Gemini 3 生图模型可按多图协议提交，旧版模型、自定义别名或上游另有更低限制时，以实际能力为准。Grok 当前不支持参考图。

单张 10 MB 与最多 9 张同时生效，因此实际原图最多约 90 MB。合计按原始文件字节计算（100×1024×1024），不是 Base64 字符数。Gemini 的 Base64 传输体积约增加三分之一；上游或代理可能另有较低限制。遇到 HTTP 413 请压缩或减少图片，不自动拆单或重试。

2. 读取模型并生成下拉选项

GET https://api.tianjinlinghang.com/v1/models
Authorization: Bearer sk-YOUR_SITE_TOKEN

返回中的 data[].id 就是模型 ID。下例仅表示结构，实际列表取决于令牌分组与模型限制：

{"data":[{"id":"gpt-image-2"},{"id":"gpt-image-2-1k"}]}

$result = Invoke-RestMethod `
  -Uri 'https://api.tianjinlinghang.com/v1/models' `
  -Headers @{ Authorization = "Bearer $env:LINGHANG_API_KEY" } `
  -TimeoutSec 15
$result.data | ForEach-Object { $_.id }

插件中的模型下拉数据源

async function loadImageModels(baseUrl, apiKey) {
  const base = new URL(baseUrl);
  if (base.protocol !== 'https:' || base.username || base.password ||
      base.search || base.hash || !base.pathname.replace(/\/+$/, '').endsWith('/v1')) {
    throw new Error('请填写以 /v1 结尾的 HTTPS API 地址');
  }
  const response = await fetch(baseUrl.replace(/\/+$/, '') + '/models', {
    headers: { Authorization: 'Bearer ' + apiKey },
    credentials: 'omit', redirect: 'error', cache: 'no-store',
    signal: AbortSignal.timeout(15000),
  });
  if (!response.ok) throw new Error('读取模型失败：HTTP ' + response.status);
  const body = await response.json();
  if (!Array.isArray(body.data)) throw new Error('模型列表格式不正确');
  const ids = body.data.map(item => item.id).filter(id =>
    typeof id === 'string' && !/video|veo|omni/i.test(id) &&
    /image|dall-e|flux|imagen|seedream|ideogram|banana/i.test(id));
  return [...new Set(ids)].sort();
}

使用返回字符串填充模型下拉框，选中值原样传给 model。更换接口或令牌时清空旧列表与旧选择，再重新拉取；失败时显示错误，不要保留其他账号的模型。手动填写也应核对当前列表。

3. GPT 文生图

POST https://api.tianjinlinghang.com/v1/images/generations，Content-Type: application/json。模型必须从当前令牌的列表中选择。

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

$body = @{
  model = 'gpt-image-2'
  prompt = '白色背景上的青绿色几何建筑，柔和日光'
  size = '1536x1024'
  quality = 'auto'
  output_format = 'png'
  moderation = 'auto'
  n = 1
  response_format = 'b64_json'
} | ConvertTo-Json
$result = Invoke-RestMethod `
  -Uri 'https://api.tianjinlinghang.com/v1/images/generations' `
  -Method Post -Headers @{ Authorization = "Bearer $env:LINGHANG_API_KEY" } `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([Text.Encoding]::UTF8.GetBytes($body)) -TimeoutSec 600
if ($result.data[0].b64_json) {
  $bytes = [Convert]::FromBase64String($result.data[0].b64_json)
  $hex = [BitConverter]::ToString($bytes)
  if ($hex.StartsWith('89-50-4E-47-0D-0A-1A-0A')) { $ext = 'png' }
  elseif ($hex.StartsWith('FF-D8-FF')) { $ext = 'jpg' }
  elseif ($bytes.Length -ge 12 -and
    [Text.Encoding]::ASCII.GetString($bytes, 0, 4) -eq 'RIFF' -and
    [Text.Encoding]::ASCII.GetString($bytes, 8, 4) -eq 'WEBP') { $ext = 'webp' }
  else { throw '返回内容不是支持的图片格式' }
  $path = Join-Path $PWD ("result-$([guid]::NewGuid()).$ext")
  [IO.File]::WriteAllBytes($path, $bytes)
  $path
} else {
  throw '未返回 Base64 图片；请按返回结果章节检查 url 或错误。'
}

4. GPT 图生图 / 参考图编辑

POST https://api.tianjinlinghang.com/v1/images/edits。使用 multipart，不能把本地文件路径作为 JSON 图片数据。

PowerShell 调用 curl.exe

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 仍为 1。不要截断参考图或拆成多次生成。result.json 保存原始响应，按返回结果章节解码图片。

浏览器插件的 FormData 请求

async function editGptImage(baseUrl, apiKey, model, prompt, files, size) {
  const base = new URL(baseUrl);
  if (base.protocol !== 'https:' || base.username || base.password ||
      base.search || base.hash || !base.pathname.replace(/\/+$/, '').endsWith('/v1')) {
    throw new Error('请填写以 /v1 结尾的 HTTPS API 地址');
  }
  if (!files.length || files.length > 9 ||
      files.some(file => !['image/png', 'image/jpeg', 'image/webp'].includes(file.type) || file.size > 10 * 1024 * 1024) ||
      files.reduce((total, file) => total + file.size, 0) > 100 * 1024 * 1024) {
    throw new Error('请选择 1 至 9 张 PNG/JPEG/WebP，单张 ≤10MB、原图合计 ≤100MB');
  }
  const form = new FormData();
  form.append('model', model);
  form.append('prompt', prompt);
  form.append('size', size);
  form.append('quality', 'auto');
  form.append('output_format', 'png');
  form.append('moderation', 'auto');
  form.append('n', '1');
  form.append('response_format', 'b64_json');
  for (const file of files) form.append('image[]', file, file.name);
  const response = await fetch(baseUrl.replace(/\/+$/, '') + '/images/edits', {
    method: 'POST', headers: { Authorization: 'Bearer ' + apiKey },
    credentials: 'omit', redirect: 'error', cache: 'no-store',
    body: form, signal: AbortSignal.timeout(600000),
  });
  if (!response.ok) throw new Error('图生图失败：HTTP ' + response.status);
  return response.json();
}

5. 模型、尺寸与价格

gpt-image-2 是模型，1536x1024 是 size，不是模型名的一部分。站内若返回 gpt-image-2-1k、gpt-image-2-2k、gpt-image-2-4k 等上游型号，须保持 ID 原样，并遵守对应档位；这类后缀不是所有厂商通用规则。

GPT Image 2 常用示例：1:1 1024x1024；16:9 1536x864；9:16 864x1536；2K 方图 2048x2048；4K 横图 3840x2160。上游别名可能另有限制。

6. Gemini / Nano Banana 图生图

从对应分组令牌的模型列表选择 gemini-3.1-flash-image 或 nano-banana-2 等实际可用型号。请求 POST https://api.tianjinlinghang.com/v1beta/models/gemini-3.1-flash-image:generateContent，使用相同 Bearer 鉴权。

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

REFERENCE_BASE64 替换为图片文件的纯 Base64，不带 data:image/...;base64, 前缀。多张图追加多个 inlineData part。文生图去掉所有图片 part，保留 text；不需要 multipart。

Gemini 3.1 Flash Image / Nano Banana 2 支持 14 种比例：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。自动时省略对应字段，不发送字符串 auto。

Pro 型号使用上述前 10 种比例及 1K/2K/4K；旧版与 Lite 不应照搬 512 或 4K 参数。当前工作台对旧版/Lite 省略 imageSize，保留其默认分辨率。

不要把这类 Gemini 原生生图模型送到本站 Gemini 渠道的 /v1/images/edits 或 /v1/images/generations；不同协议不能只靠改模型名称互换。

7. Grok 当前能力

当前站内 xAI 适配器仅按以下文生图字段转发：

{
  "model": "grok-imagine-image",
  "prompt": "白色背景上的青绿色几何建筑",
  "n": 1,
  "response_format": "b64_json"
}

端点为 POST /v1/images/generations。本页不宣称 Grok 图生图、尺寸或质量控制已开通。上传参考图时应禁用提交或提示选择支持图生图的 GPT / Gemini，不能悄悄丢弃参考图。

8. 图片返回与保存

GPT / Grok 优先请求 response_format: "b64_json"，从 data[].b64_json 解码。部分上游仍可能返回 data[].url，需单独处理。

{"data":[{"b64_json":"BASE64_IMAGE_BYTES"}]}

Gemini 图片位于 candidates[].content.parts[].inlineData，部分接口使用 inline_data；读取 mimeType / mime_type 与 data，仅接收 PNG/JPEG/WebP，排除 thought: true 图片。

{"candidates":[{"finishReason":"STOP","content":{"parts":[
  {"inlineData":{"mimeType":"image/jpeg","data":"BASE64_IMAGE_BYTES"}}
]}}]}

thoughtSignature 不是 thought: true，不能因此丢弃正常图片。遇到 promptFeedback.blockReason、失败的 finishReason、仅文本或空图片时显示具体原因，不能仅凭 HTTP 200 就显示成功。HTTPS fileData.fileUri 可作为原始图片链接供用户打开。

下方 Python 示例会按图片文件签名解码保存；URL-only 响应只提示检查，不自动访问第三方地址。

9. Codex 与第三方插件接入

生图插件自己的模型下拉应调用 /v1/models。这与 Codex 主对话模型选择器是两回事；图片端点不会仅因写进配置就变成 Responses 对话模型。

截图中只有「清晰度」下拉、自动拼模型名的插件需要增加真正的模型选择和参考图上传分支。更新本文档不会自动修改已经安装的插件。

直接交给插件开发者 / Codex 的修改要求

阅读 https://api.tianjinlinghang.com/docs/image/api-guide-20260909.md，
按本站生图工作台的协议更新插件：
1. 使用客户提供的 API Base URL 和令牌读取 GET /v1/models，
   data[].id 填充独立模型下拉，不再根据 1K/2K/4K 和比例拼模型名。
2. GPT 无参考图时 POST /v1/images/generations JSON；
   有参考图时 POST /v1/images/edits multipart，真实文件字段 image[]。
   上传选择、计数和提交上限统一为9张；单张10MB不变，原图合计改为100MB。
   全部参考图放在同一请求，不截断、不拆单；旧版模型仍遵守实际能力限制。
3. Gemini / Nano Banana 使用 /v1beta/models/{model}:generateContent，
   text + inlineData，responseModalities 包含 TEXT 和 IMAGE。
4. 分模型显示尺寸选项；Grok 当前不启用图生图或尺寸控制。
5. 解析 GPT 的 b64_json/url 和 Gemini 的 inlineData/inline_data；
   显示无图、审核拦截和 HTTP 错误。提交锁防重复，禁用自动生成重试。
6. 令牌只保存在客户本机安全存储，切换接口或令牌即清空旧模型列表，
   不向返回图片 URL、日志、遥测或第三方发送本站令牌。
先使用模拟响应验证，不自动发起可能扣费的真实测试。

Python 3 调用示例

下载 image-client-20260909.py。依赖 requests，令牌从环境变量读取。模型必须选择当前列表中存在的 ID：

python -m pip install requests

# 只读取模型，不生成图片
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

默认调用本站；手动接口可用 --base-url https://your-gateway.example/v1，只使用为该接口单独配置的令牌。每次执行最多一条生成 POST，不做自动重试。

10. 报错排查