跳到主要内容
Router One
Router One
图片生成

创建图片编辑（图生图）

根据文本指令改写参考图（图生图）：风格迁移、替换背景、修改主体、局部修复等。与文生图一样是同步接口，请求会在图片生成完成后返回；典型耗时 5-30 秒，建议客户端 HTTP 超时设置不少于 60 秒。 与其他 JSON 接口不同，该接口使用 `multipart/form-data`，参考图以文件形式上传。传一个 `image` 字段即可；所选模型支持多参考图时，可重复传多个 `image` 字段（也接受 `image[]`）。每个文件必须是图片格式，大小不超过 25 MB。 响应结构与计费和文生图一致：`data` 数组长度等于实际生成的图片数量，`url` 方式返回的链接有效期约 1 小时，如需长期保存请下载或转存。

POST
/v1/images/edits

Authorization

AuthorizationBearer <token>

使用 API Key 进行认证。在 Router One 控制台获取你的 API Key，格式为 sk-xxx。

In: header

Request Body

modelstring

模型 ID。需选择支持图生图能力的模型，可在控制台模型市场查询。

promptstring

描述如何改写参考图的文本指令，例如「把这张照片变成水彩画风格」「把背景换成日落海滩」。建议长度不超过 4000 字符。

Lengthlength <= 4000
imagefile

参考图文件（PNG / JPEG / WebP 等）。所选模型支持多参考图时，可重复传多个 image 字段（也接受 image[]）。单个文件不超过 25 MB。

Formatbinary
n?integer

本次请求生成的图片数量。按张数计费。

Default1
Range1 <= value <= 10
size?string

输出图片尺寸，格式 宽x高（像素），例如 1024x1024。按原值传给模型——Router One 不做校验，各模型支持的尺寸不同，部分模型会忽略该字段。模型拒绝的尺寸会返回 400 invalid request (upstream rejected with status 400)。支持的尺寸以该模型的目录页为准。

quality?string

质量提示，按原值传给模型。Router One 不做校验；各模型接受的取值（若有）不同，没有质量控制项的模型会忽略它。模型拒绝的取值会返回 400 invalid request (upstream rejected with status 400)。计费按张、以该模型目录页的单价为准。Grok Imagine 的高画质档是独立模型 grok-imagine-image-quality，不是 quality 取值。

response_format?string

响应中图片的返回方式。

  • url（默认）：返回 CDN URL，有效期约 1 小时，需自行下载或转存
  • b64_json：直接在响应中返回 base64 编码的图片字节，响应体较大但无需额外下载
Default"url"
Value in"url" | "b64_json"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.router.one/v1/images/edits" \  -F model="gemini-3.1-flash-image-preview" \  -F prompt="string" \  -F image="string"
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://cdn.router.one/img/def456.png"
    }
  ]
}
{
  "error": {
    "message": "invalid request body: image is required",
    "type": "invalid_request_error",
    "code": "INVALID_REQUEST",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "invalid api key",
    "type": "authentication_error",
    "code": "AUTH_INVALID_API_KEY",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}

{
  "error": {
    "message": "insufficient balance: top up at https://router.one/deposit",
    "type": "billing_error",
    "code": "INSUFFICIENT_BALANCE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "internal error",
    "type": "api_error",
    "code": "INTERNAL_ERROR",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "content moderation unavailable",
    "type": "service_unavailable",
    "code": "MODERATION_UNAVAILABLE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}
{
  "error": {
    "message": "provider is currently unavailable",
    "type": "service_unavailable",
    "code": "PROVIDER_UNAVAILABLE",
    "request_id": "290dd478f91d8aec68f7535e871376eb"
  }
}