Skip to content
Router One
Router One

Create Image Generation

Generate images from a text prompt. This is a synchronous endpoint; the request returns once generation completes. Typical generation takes 5-30 seconds — set a client HTTP timeout of at least 60 seconds. The `data` array length in the response equals the number of images actually generated, and is what you are billed for. When `response_format` is `url`, the returned image URLs have an expiration (typically 1 hour); download or re-host them if you need them long-term.

POST
/v1/images/generations

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 generation; check the console model marketplace.

promptstring

Text prompt for image generation. More specific and visually evocative prompts usually produce better results. Recommended length under 4000 characters.

Lengthlength <= 4000
n?integer

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

Default1
Range1 <= value <= 10
size?string

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/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-image-2",    "prompt": "An orange kitten wearing an astronaut helmet, floating in starry space, cinematic lighting"  }'
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://cdn.router.one/img/abc123.png",
      "revised_prompt": "An orange kitten wearing an astronaut helmet, floating in starry space, cinematic lighting"
    }
  ]
}
{
  "error": {
    "message": "requested model is not available",
    "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"
  }
}