Skip to content
Router One
Router One

Create Image Edit

Transform reference images with a text instruction (image-to-image): style transfer, background replacement, subject changes, retouching, and similar edits. Like image generation this is a synchronous endpoint; typical generation takes 5-30 seconds — set a client HTTP timeout of at least 60 seconds. Unlike the JSON endpoints, requests use `multipart/form-data` because the reference images are uploaded as files. Send one `image` field, or repeat it (`image[]` is also accepted) to pass multiple reference images when the chosen model supports that. Each file must be an image and is limited to 25 MB. The response format and billing follow image generation: the `data` array length equals the number of images actually generated, and `url` results expire after about 1 hour — download or re-host them if you need them long-term.

POST
/v1/images/edits

Authorization

AuthorizationBearer <token>

Authenticate with your API Key. Get your API Key in the Router One console; the format is sk-xxx.

In: header

Request Body

modelstring

Model ID. Choose a model that supports image-to-image editing; check the console model marketplace.

promptstring

Text instruction describing how to transform the reference image(s) — e.g. "turn this photo into a watercolor painting" or "replace the background with a sunset beach". Recommended length under 4000 characters.

Lengthlength <= 4000
imagefile

Reference image file (PNG / JPEG / WebP, etc.). Repeat the image field to upload multiple reference images for models that support it (image[] is also accepted). Up to 25 MB per file.

Formatbinary
n?integer

Number of images to generate in this request. Billed per image.

Default1
Range1 <= value <= 10
size?string

Output image size as WIDTHxHEIGHT in pixels, e.g. 1024x1024. Passed to the model as sent — Router One does not validate it, accepted sizes differ per model, and some models ignore it. A size the model rejects returns 400 invalid request (upstream rejected with status 400). See the model page for its supported sizes.

quality?string

Quality hint passed to the model as sent. Router One does not validate it; accepted values, if any, differ per model, and models without a quality control ignore it. A value the model rejects returns 400 invalid request (upstream rejected with status 400). Billing is per image at the model's catalog unit price. For Grok Imagine, the higher-fidelity tier is the separate model grok-imagine-image-quality rather than a quality value.

response_format?string

How the image is returned.

  • url (default): a CDN URL valid for about 1 hour; download or re-host as needed
  • b64_json: base64-encoded image bytes in the response; larger body, no extra download
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"
  }
}