이 페이지는 현재 중국어로만 제공됩니다. 내비게이션과 메뉴는 한국어로 표시됩니다.

图片 API 指南

使用 POST /v1/images/generations 将提示词转换为图像。在支持参考素材的模型和映射上，还可上传图片后以 file_id 引用。接口通常直接返回结果，不采用视频接口的任务轮询流程。

准备模型与参数

在控制台选择具有图片 API 映射的公共模型，把示例 YOUR_MODEL_ID 替换为真实 ID。Key 只保存在服务端环境变量 INONEAPI_API_KEY 中。

参数使用建议
model、prompt必填。提示词写清主体、构图、风格、文字和约束。
n可选输出数量；先用 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 类型，转换 source 为 COS 签名 URL 后保留 role，再交给模型映射；不会自动提供任意图片编辑能力。素材角色和数量以模型为准，文件必须处于 ready 且对象仍存在。文件生命周期为 1 天，签名 URL 有效 5 分钟，异步读取必须落在有效窗口内。

流式输出与能力边界

模型原生支持时可使用 stream: true，并按服务商规定解析 SSE；partial_images 仅在对应模型支持时使用。部分图像事件不是额外的最终图片，也不能把整个 SSE 响应当 JSON 图片数组。

需要 request DSL 转换的请求不支持流式转换。此接口不提供通用图片任务查询、variations 或自动异步轮询；文件引用也不会新增独立图片编辑端点。需要分析一张图片并返回文字时，请使用支持图片输入的文本 API。

错误处理与生产建议

400 检查尺寸、质量、格式、参考角色和模型能力；401/403 检查 Key 与模型权限；429 遵循 Retry-After 并降低并发；502 可能是上游响应或映射归一化失败。非成功 HTTP 响应先按错误处理，不要直接读 data[0]。

生成超时后上游可能已完成并计费，应设置合理等待时间，避免自动无限重发。Base64 会增加响应体和内存占用，DSL 响应默认缓冲上限为 32 MiB；控制数量、分辨率和并发。记录 X-Gateway-Trace-ID 便于排障。

POST /v1/images/generations · POST /v1/files · 文件指南

이미지 · 문서 · InOneAPI