图像生成

如需引用文件，先通过文件 API 上传素材，再使用返回的 file_id。网关负责转换，服务商是否接受由上游返回结果。

素材可以使用 input_references: [{"type":"image","role":"reference","source":{"type":"file","file_id":"..."}}]。type 必须匹配实际素材的 image/audio/video 类型。网关会读取该文件并按所选服务商的协议传入，role 保持不变；其他必填字段仍然必填。图片、视频和语音接口的 input_references 属于 InOneAPI 扩展。

公共协议使用 OpenAI Images API。生成入口 POST /v1/images/generations。各家服务商的参数与响应差异由平台统一转换，调用方只需按公共协议填写。InOneAPI 要求显式 model，不能依赖 OpenAI 的默认模型。

最小请求

先将 YOUR_MODEL_ID 替换为模型详情页的完整 ID，不要自行添加服务商前缀。可选参数按所选模型能力填写；应用请求头默认注释。

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/images/generations" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A blue bird on a white background"
}'

生成参数完整参考

参数	类型	生成参数完整参考
`model`	string	必填公共模型 ID；请求转发时平台会替换为实际服务商的模型 ID。
`prompt`	string	必填提示词，描述主体、构图、风格、文字及约束。长度上限以模型为准。
`n`	integer	可选图片数量。Qwen-Image 系列（2.1/3.0）支持 1–6 张，默认 1；Seedream 系、GLM-Image、混元图像等模型不支持，传入也只会生成 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	可选布尔，默认非流式。仅部分模型支持流式返回；模型不支持时返回 400 `PROTOCOL_STREAM_UNSUPPORTED`。
`partial_images`	integer	可选整数 0–3，仅流式时使用；是最多部分图像事件数，不是输出图片总数；最终图像可能更早返回。

n 参数支持范围

n 并非所有图像模型都支持：只有上游服务商支持多图输出、且平台已完成参数映射的模型才会生效。当前支持的模型为 Qwen-Image 系列——qwen-image-2.1-pro、qwen-image-3.0、qwen-image-3.0-pro，上限 1–6 张，默认 1 张。模型详情页能力区显示「输出数量」标识即表示支持。

不支持的模型（Seedream 系、GLM-Image、混元图像）每次请求只返回 1 张图片；传入 n 不会报错，也不会多图。Seedream 系的上游多图能力是另一套组图参数（sequential_image_generation），语义与数量不同，暂未开放。模型详情页的 API 调用指南弹框也会对不支持的模型给出同样提示。

按模型能力拆分完整示例

不存在能在所有模型上合法的“全部参数组合”。下面分别展示 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": "YOUR_MODEL_ID",
  "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":"YOUR_MODEL_ID","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":"YOUR_MODEL_ID","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 秒级生成时间，整数；视频接口的时间字段格式由服务商决定，两者不能混用。
`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 为输入拆分。实际计费维度以该模型的计费方式为准，可能按 token 或其他计量。

错误、流式与边界

HTTP 400 通常是参数或媒体格式不符合该模型的要求；401/403 检查密钥和权限；429 按 Retry-After 退避；502 通常是服务商返回了平台无法解析的响应。记录 X-Gateway-Trace-ID，不记录密钥或敏感图像。生成请求超时可能已在服务商侧完成，不应无条件重试。接口返回同步结果或服务商的 SSE 事件流，不是视频式任务接口；没有通用图像任务查询、异步轮询转换或 variations 端点。流式返回的是服务商原生事件，平台不改写其结构。Base64 结果会显著增大响应体，单个响应有大小上限，超出时请求失败；建议优先使用 URL 输出并及时下载。

在线体验

控制台 Playground 和模型详情的“立即体验”会按模型的输出模态调用此接口。图像结果支持 data[].url 与 data[].b64_json，可直接预览和保存。若模型同时输出文本与图像，可在输入区选择输出类型。顶部模型筛选只匹配输出能力。