Images

Use POST /v1/images/generations for OpenAI-style image generation and POST /v1/images/edits for OpenAI-style image editing.

POST https://api.rout.my/v1/images/generations

Request

curl https://api.rout.my/v1/images/generations \
  -H "Authorization: Bearer $ROUTMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/image-model-id",
    "prompt": "A clean product photo of a translucent blue cube on a white table",
    "n": 1,
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

Request fields

Field	Type	Required	Notes
model	string	Yes	Exact image model ID from /v1/models.
prompt	string	Yes	Text description of the image.
response_format	string	No	url (default) or b64_json; GoRouter normalizes client delivery.
n	integer	No	Number of images requested. Defaults to provider behavior when omitted.
size	string	No	OpenAI-style size value, when supported by the model.
quality	string	No	Quality hint, when supported by the model.
style	string	No	Style hint, when supported by the model.
background	string	No	auto, opaque, or transparent for supported GPT Image models.
output_format	string	No	png, jpeg, or webp.
output_compression	integer	No	0–100, for JPEG or WebP; zero is preserved.
moderation	string	No	auto or low for GPT Image models.
user	string	No	Accepted for compatibility but stripped before upstream requests.
image_config	object	No	Provider-neutral image settings.

image_config

Field	Type	Notes
aspect_ratio	string	Common values include 1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4, and 21:9.
image_size	string	Common values include 1K, 2K, and 4K. Values are forwarded to the provider when supported.

Response

For /v1/images/generations, the default (response_format: "url") returns each image in data[].url. GoRouter downloads remote images when needed, validates their encoding and image type, and constructs data:image/png;base64,... (or JPEG/WebP/GIF based on the actual bytes). Upstream HTTP(S) URLs are never returned to clients.

{
  "created": 1744000000,
  "data": [
    {
      "url": "data:image/png;base64,iVBORw0KGgo...",
      "revised_prompt": "A clean product photo of a translucent blue cube..."
    }
  ]
}

Explicit response_format: "b64_json" returns plain base64 without a data: prefix:

{
  "created": 1744000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

Use data[].url directly as an image src. Decode b64_json or add the appropriate data URI prefix before displaying it. response_format is applied locally and is not sent upstream. Invalid inline image data returns 502 without generating another image. Streaming image edits retain their existing format.

Image edits

Use POST /v1/images/edits when the model should transform one or more input images.

POST https://api.rout.my/v1/images/edits

JSON requests should use images as an array. Multipart requests can use OpenAI-style image file fields.

curl https://api.rout.my/v1/images/edits \
  -H "Authorization: Bearer $ROUTMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/image-edit-model-id",
    "prompt": "Keep the product, replace the background with a clean studio gradient",
    "images": [
      {
        "image_url": "https://example.com/input.png"
      }
    ],
    "n": 1,
    "size": "1024x1024"
  }'

Common edit fields include model, prompt, images, image, mask, n, size, quality, background, input_fidelity, moderation, output_compression, output_format, partial_images, and stream. The user field is accepted for compatibility but stripped before upstream requests.

Quota accounting

GPT Image 2 and GPT Image 2.5

openai/gpt-image-2, openai/gpt-image-2.5-flare, and openai/gpt-image-2.5-sunburst (including their published dated snapshots) use native token usage on /v1/images/generations and /v1/images/edits. The model's token_multiplier is the image-output token multiplier. Input modalities are weighted relative to the $30-per-million image-output rate:

weighted_tokens = image_output
                + uncached_text_input * 5/30
                + uncached_image_input * 8/30
                + cached_text_input * 1.25/30
                + cached_image_input * 2/30
quota = ceil(weighted_tokens * effective_token_multiplier)

Cached tokens are subsets of input tokens and are not counted twice. The effective multiplier includes any pricing-group global multiplier. A zero multiplier remains free. With an effective multiplier of 27.5, a response reporting 100 text input tokens and 2,000 image output tokens uses 55,459 quota units. Quality and size affect provider token usage; no extra quality multiplier or image-count floor is applied to complete metered usage.

Admission still requires and atomically reserves the conservative per-image estimate below. After successful delivery, settlement refunds unused quota or charges additional usage. Provider failure or failed delivery releases the reservation. This admission estimate is not the final price.

If usage is absent, inconsistent, or lacks a required modality/cache breakdown, the existing per-image/total-token formula below remains the fallback. These requests are marked gpt_image_usage_fallback with a reason in usage analytics and IMAGE_USAGE_FALLBACK in server logs; missing usage never means a free image. Streaming image edits read usage from completed SSE events without changing stream bytes. If the stream does not expose usable usage, the fallback applies.

Subscriber quota and reseller dollar billing remain separate. This change does not modify reseller price cards or provider-reported dollar costs.

Other image models and incomplete-usage fallback

Image generation and image edits deduct quota from the number of output images, multiplied by the model's token_multiplier:

Requested size	Base quota units per image
empty, 1K, 2K, or other non-4K values	5,000
4K	12,500

Provider-reported usage.total_tokens can also be used internally when available, but it cannot reduce the billable base below the output-image floor. The effective base is:

max(provider_usage.total_tokens, output_images * base_quota_units_per_image)

For /v1/images/edits, the default floor is 5,000 quota units per output image. The public response can include provider usage when the upstream returns it, but private billing metadata is not exposed.

Chat image generation

Some image-capable chat models use /v1/chat/completions with modalities: ["image", "text"]. See Chat Completions for that request shape.

Image edits use the same validated delivery: b64_json by default or a data URI with response_format: "url". Streaming edits preserve image events and usage, while routing metadata and raw upstream errors are removed.