图像生成

公共协议使用 OpenAI Images API。生成入口 POST /v1/images/generations。原生兼容直接透传，不兼容由管理员使用 JSON DSL 映射。InOneAPI 要求显式 model，不能依赖 OpenAI 的默认模型。

生成参数完整参考

Parameter	Type	生成参数完整参考
`model`	string	必填公共模型 ID；网关替换为选中映射的上游 ID。
`prompt`	string	必填提示词，描述主体、构图、风格、文字及约束。长度上限以模型为准。
`n`	integer	可选图片数量，通常 1–10；部分模型只允许 1。省略使用上游默认值。
`size`	string	可选 WIDTHxHEIGHT 或 auto。常见 1024x1024、1536x1024、1024x1536；模型各有约束，不由网关缩放。
`quality`	string	可选 auto/low/medium/high（GPT Image 类），或 standard/hd（部分旧模型）；不是同一模型全支持。
`style`	string	可选 vivid/natural，仅适用支持风格参数的模型，不与所有 GPT Image 参数通用。
`response_format`	string	可选 url/b64_json，适用于支持返回格式选择的服务商。GPT Image 原生始终 Base64，不支持此字段，须省略。
`background`	string	可选 auto/opaque/transparent。透明背景需要支持它的模型及 png/webp，不能配 jpeg。
`output_format`	string	可选 png/jpeg/webp。仅在模型支持时传入，默认由上游决定。
`output_compression`	integer	可选整数 0–100，仅 jpeg/webp 有损输出使用；不用于 png。
`moderation`	string	可选 auto/low；仅在模型支持时传入。不是绕过服务商审核。
`user`	string	可选业务终端用户标识；避免邮箱、手机号等敏感信息。
`stream`	boolean	可选布尔，默认非流式。仅原生兼容支持流式透传；需要 request DSL 的请求不可流式转换。
`partial_images`	integer	可选整数 0–3，仅流式时使用；是最多部分图像事件数，不是输出图片总数；最终图像可能更早返回。

按模型能力拆分完整示例

不存在能在所有模型上合法的“全部参数组合”。下面分别展示 GPT Image 类和旧版风格/URL 类。所有可选字段都在表中解释；partial_images 见流式示例。示例模型 ID 必须替换为控制台已启用的真实 ID。

curl https://api.inoneapi.com/v1/images/generations \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "provider/image-model",
  "prompt": "A blue bird on a white background",
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "background": "opaque",
  "output_format": "jpeg",
  "output_compression": 90,
  "moderation": "auto",
  "user": "user_123",
  "stream": false
}'

{"model":"provider/legacy-image-model","prompt":"A blue bird","n":1,"size":"1024x1024","quality":"hd","style":"vivid","response_format":"url","user":"user_123"}

curl -N https://api.inoneapi.com/v1/images/generations \
  -H "Authorization: Bearer $INONEAPI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"provider/image-model","prompt":"A blue bird","stream":true,"partial_images":2}'

响应与结果读取

{
  "created":1788580800,
  "data":[{"b64_json":"REPLACE_WITH_IMAGE_BYTES"}],
  "background":"opaque",
  "output_format":"jpeg",
  "size":"1024x1024",
  "quality":"high",
  "usage":{"input_tokens":100,"output_tokens":1000,"total_tokens":1100,"input_tokens_details":{"text_tokens":60,"image_tokens":40}}
}

Field	响应与结果读取
`created`	Unix 秒级生成时间，整数；不同于视频接口的 ISO 时间字符串。
`data[]`	结果数组，按服务商顺序。长度通常对应 n，但不能假定失败时也有完整数量。
`data[].b64_json`	Base64 原始图像字节，不含 data URL 前缀；按 output_format 解码保存。
`data[].url`	临时下载地址，只有服务商支持 URL 输出时存在；需及时下载，不保证长期托管。
`data[].revised_prompt`	服务商实际使用的修订提示词，可选，不等于原始 prompt。
`background / output_format / size / quality`	可选实际背景、格式、尺寸和质量元数据，以服务商返回为准。
`usage`	可选 token 计量；不是所有服务商返回。不要把缺失 usage 当作免费。
`usage.input_tokens / output_tokens / total_tokens`	可选输入、输出、总 token 数。input_tokens_details.text_tokens/image_tokens 为输入拆分。服务商计费仍由独立 metering/billing DSL 定义。

错误、流式与边界

HTTP 400 通常是参数、媒体格式或 DSL 输入不符合配置；401/403 检查密钥和权限；429 按 Retry-After 退避；502 可能是响应归一化失败或响应超过 DSL 缓冲限制。记录 X-Gateway-Trace-ID，不记录密钥或敏感图像。生成请求超时可能已在上游完成，不应无条件重试。接口是同步结果或原生 SSE，不是视频式任务接口；没有通用图像任务查询、异步轮询转换或 variations 端点。DSL 不转换流式事件。Base64 较大，转换响应受 GATEWAY_RESPONSE_BUFFER_BYTES 限制（默认 32 MiB），需按并发内存预算调整。

管理员与 AI 配置说明

图像映射填写 image_path，原生配置使用 {"version":1}。生成用 request/response。原生协议开关默认开启；关闭后可编辑和测试 DSL。严格服务商使用 mode=replace，避免保留无关字段。完整 schema、逐字段映射、四方向 fixture、枚举和能力缺口检查见仓库 docs/image-protocol-dsl.md 与 docs/protocol-mapping-dsl.schema.json。协议 DSL 不定义价格，计量读取上游原始响应。