生图 API

使用 OpenAI 兼容的 Images 接口生成或编辑图片，查看请求示例与返回格式。

接口域名为 https://api.flatrouter.com。通过 POST /v1/images/generations 提交提示词，也可通过 POST /v1/images/edits 上传图片并编辑。图片结果会随本次请求返回；耗时较长的请求可改用异步任务，提交后轮询获取结果。

使用前确认

在控制台 → API Keys 创建 API Key，并选择支持所需图片模型、已开启生图权限的分组。请求使用 Authorization: Bearer <API Key> 鉴权。

图片生成

将 YOUR_FLATROUTER_API_KEY 替换为你的 API Key：

curl https://api.flatrouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_FLATROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗边，水彩插画风格",
    "n": 1,
    "response_format": "b64_json"
  }'

参数	说明
`model`	图片模型；示例使用 `gpt-image-2`
`prompt`	描述要生成的图片
`n`	生成数量；示例请求 1 张
`response_format`	示例使用 `b64_json`，以 Base64 编码返回图片

也可使用 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst；实际可用模型以 API Key 所属分组为准。

图片编辑

通过 POST /v1/images/edits 提交 multipart/form-data 请求。替换 API Key，并将 /path/to/source.png 替换为本地输入图片路径：

curl -X POST https://api.flatrouter.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_FLATROUTER_API_KEY" \
  -F "image=@/path/to/source.png;type=image/png" \
  -F "model=gpt-image-2" \
  -F "prompt=将背景改成海边，保留主体" \
  -F "response_format=b64_json"

curl -F 会自动设置 Content-Type 和 multipart boundary，无需手动添加。

参数	说明
`image`	要编辑的图片文件；多张输入可重复使用 `image[]` 文件字段
`prompt`	必填，描述希望对输入图片进行的修改
`model`	图片模型；示例使用 `gpt-image-2`，可用模型以分组为准
`response_format`	示例使用 `b64_json`，返回 Base64 图片数据
`mask`	可选的蒙版文件，通过 multipart 文件字段上传；具体要求取决于所用模型

编辑接口与生成接口共用下面的返回格式。

返回格式

以下为非流式响应示意，图片数据已省略：

{
  "created": 1788912000,
  "data": [
    {
      "b64_json": "<图片的 Base64 数据>"
    }
  ]
}

created 是响应的 Unix 时间戳（秒），data 是图片结果数组。示例请求的一张图片位于 data[0].b64_json，将其 Base64 解码即可得到图片文件内容。响应可能包含其他字段。

异步任务

生成高分辨率或多张图片可能耗时较长。如果你的客户端、代理或网关对单个 HTTP 请求有超时限制，可改用异步接口：提交后立即拿到任务 ID，再轮询查询结果，无需一直保持连接。

方法与路径	说明
`POST /v1/images/generations/async`	提交生成任务，请求体与 `/v1/images/generations` 相同
`POST /v1/images/edits/async`	提交编辑任务，`multipart/form-data` 请求体与 `/v1/images/edits` 相同
`GET /v1/images/tasks/{task_id}`	查询任务状态与结果

模型、分组权限和计费与同步接口一致。异步接口不支持流式输出，请求中不要设置 "stream": true。

提交任务

在同步接口的路径后加上 /async，请求体保持不变：

curl https://api.flatrouter.com/v1/images/generations/async \
  -H "Authorization: Bearer YOUR_FLATROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗边，水彩插画风格",
    "n": 1
  }'

提交成功返回 HTTP 202 Accepted：

{
  "id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "task_id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "object": "image.generation.task",
  "status": "processing",
  "created_at": 1788912000,
  "expires_at": 1788998400,
  "poll_url": "/v1/images/tasks/imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60"
}

poll_url 是查询路径，拼接在 https://api.flatrouter.com 之后使用；响应头 Location 也是同一路径。请求参数错误、分组未开启生图权限等问题会在提交时直接返回错误，不会创建任务。

查询任务

使用提交任务的同一个 API Key 查询：

curl https://api.flatrouter.com/v1/images/tasks/imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60 \
  -H "Authorization: Bearer YOUR_FLATROUTER_API_KEY"

查询接口的 HTTP 状态码为 200，任务状态看 status 字段：

`status`	含义
`processing`	仍在生成，稍后再查
`completed`	已完成，结果在 `result` 中
`failed`	已失败，原因在 `error` 中

任务完成时的响应：

{
  "id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "task_id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "image_url": "https://img.flatrouter.com/<图片路径>",
  "result": {
    "created": 1788912095,
    "data": [
      {
        "url": "https://img.flatrouter.com/<图片路径>"
      }
    ]
  },
  "created_at": 1788912000,
  "completed_at": 1788912095,
  "expires_at": 1788998495
}

result 与同步接口的返回格式相同，区别是图片以链接形式返回：每张图片的地址在 result.data[].url，不包含 b64_json（即使请求中设置了 "response_format": "b64_json"）。image_url 是第一张图片的链接，便于只生成一张图时直接读取。

任务失败时的响应：

{
  "id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "task_id": "imgtask_3f2a9c1e8b7d4a6f9e0c1b2a3d4e5f60",
  "object": "image.generation.task",
  "status": "failed",
  "http_status": 502,
  "error": {
    "type": "api_error",
    "message": "Upstream request failed"
  },
  "created_at": 1788912000,
  "completed_at": 1788912095,
  "expires_at": 1788998495
}

http_status 是这次生成对应的 HTTP 状态码，error 与同步接口的错误对象格式相同。

轮询建议与限制

建议每 3 秒查询一次；任务处于 processing 时，响应头 Retry-After 会给出建议间隔（秒）。
单个任务最长执行 30 分钟，超时后状态变为 failed。
任务记录在最后一次状态变化后保留 24 小时（见 expires_at），过期后查询返回 404。拿到图片链接后请及时下载保存。
任务只能由提交它的 API Key 查询；任务 ID 不存在、已过期或属于其他 API Key（包括同一账号下的其他 Key）时，均返回 404。