图片 API 指南
使用 POST /v1/images/generations 将提示词转换为图像。支持参考素材的模型还可上传图片后以 file_id 引用。接口通常直接返回结果，不采用视频接口的任务轮询流程。
准备模型与参数
在控制台选择支持图片生成的公共模型，把示例 YOUR_MODEL_ID 替换为真实 ID。Key 只保存在服务端环境变量 INONEAPI_API_KEY 中。
| 参数 | 使用建议 |
|---|---|
model、prompt | 必填。提示词写清主体、构图、风格、文字和约束。 |
n | 可选输出数量；仅部分模型支持（当前为 Qwen-Image 系列，1–6 张），不支持的模型每次只生成 1 张且不报错。先用 1 验证，以模型详情页「输出数量」能力标识为准。 |
size | 可选尺寸；允许值由模型决定，不是网关缩放指令。 |
quality | 模型专属质量枚举，不能混用不同模型的取值。 |
output_format、background | 仅对支持的模型设置；透明背景需要兼容格式，如 PNG/WebP。 |
response_format | 只有支持选择的服务商才接受 url 或 b64_json，并非通用必填字段。 |
建议先发送最小请求，再逐项添加模型明确支持的参数。
从提示词生成图片
以下代码使用 cURL 或服务端 Node.js 20+。不要在客户端页面嵌入 API Key。
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 clean product photo of a white ceramic cup on a gray background","n":1}'读取和保存结果
成功响应通常含 created 和 data[]。每项可能是 b64_json 或 url，也可能带 revised_prompt。usage 不是每个服务商都返回，缺失不代表免费。
Base64 是原始图像字节编码，不含 data URL 前缀。示例保存为 .bin，避免在尚未确认实际格式时错误标注 PNG/JPEG；确认响应 output_format 或文件真实类型后使用相应扩展名。不要通过改扩展名进行格式转换。
URL 通常是临时地址，应及时下载到自己的存储。服务端下载不要附带 InOneAPI Key，并校验目标地址、文件大小与超时。浏览器端保留直接链接，不要假定服务商已开放跨域 fetch。批量生成应逐项处理，不能默认永远恰好返回 n 张。
{
"created": 1789430400,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}使用参考图片
先调用文件上传接口，并确保生成时使用同一 API Key。以下请求仅适用于明确支持参考图片的模型：
{
"model": "YOUR_MODEL_ID",
"prompt": "Keep the reference composition and use a white background.",
"input_references": [
{
"type": "image",
"role": "reference",
"source": {
"type": "file",
"file_id": "file_ioa_0123456789abcdef0123456789abcdef"
}
}
]
}input_references 是 InOneAPI 扩展。网关会校验文件归属和 image 类型，保留 role 后把一个临时可访问的地址交给所选模型；不会因此新增任意图片编辑能力。素材角色和数量以模型为准，文件必须处于 ready 且内容仍可读取。文件保存 1 天，临时地址有效 5 分钟，异步任务必须在这一窗口内取到素材。
流式输出与能力边界
模型支持时可使用 stream: true，并按服务商规定解析 SSE；partial_images 仅在对应模型支持时使用。部分图像事件不是额外的最终图片，也不能把整个 SSE 响应当 JSON 图片数组。
需要参数转换的模型不支持流式返回，会返回 400 PROTOCOL_STREAM_UNSUPPORTED。此接口不提供通用图片任务查询、variations 或自动异步轮询；文件引用也不会新增独立图片编辑端点。需要分析一张图片并返回文字时，请使用支持图片输入的文本 API。
错误处理与生产建议
400 检查尺寸、质量、格式、参考角色和模型能力；401/403 检查 Key 与模型权限；429 遵循 Retry-After 并降低并发；502 通常是服务商返回了平台无法解析的响应。非成功 HTTP 响应先按错误处理，不要直接读 data[0]。
生成超时后上游可能已完成并计费，应设置合理等待时间，避免自动无限重发。Base64 会显著增大响应体，单个响应有大小上限，超出时请求失败；请控制数量、分辨率和并发。记录 X-Gateway-Trace-ID 便于排障。