---
title: "Routed image generation"
method: POST
path: "/v1/generate/image"
tags: ["Model Router"]
---

# Routed image generation

`POST /v1/generate/image`

Start an image generation task using a saved Model Router config instead of naming a model.

## Headers

- `X-Runway-Version` '2024-11-06', required

## Request body

- object
  - `configId` string, required — The slug of a saved Model Router config to route this request with.
  - `input` object, required — Model-agnostic image generation input. The router selects a model and maps these options to it.
    - `promptText` string, required — A text prompt describing the desired image.
    - `referenceImages` object[] — Optional reference images for models that support them. Tags are assigned per model when omitted.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9' | '2:3' | '3:2' | '4:5' | '5:4' — Desired aspect ratio. Models that do not support the requested aspect are excluded.
    - `resolution` '1k' | '2k' | '4k' — Desired megapixel tier. Models that do not support the requested tier are excluded.
    - `outputCount` integer — Number of images to generate (1-10). Models that cannot produce the exact count are excluded and cost scales with this value.
    - `seed` integer — A seed for reproducible generation. Only gen4_image and gen4_image_turbo accept this field.
    - `contentModeration` object — Settings that affect the behavior of the content moderation system.
      - `publicFigureThreshold` 'auto' | 'low' — When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.

## Response `200`

The created task and routing decision. Poll GET /v1/tasks/:id for the result.

- object
  - `id` string, uuid, required — The ID of the created task. Poll GET /v1/tasks/:id for the result.
  - `routing` object, required — Metadata describing which model the router selected and why.
    - `model` string, required — The public name of the model the router selected.
    - `provider` string, required — The provider of the selected model.
    - `configId` string, required — The slug of the router config that was applied to this request.
    - `resolvedSettings` object, required — The resolved config settings the router used for this request.
      - `optimizeFor` 'cost' | 'latency' | 'quality', required — The single optimization preference the config selected, used as the soft weighting when scoring eligible models.
      - `priceCeiling` number, nullable, required — The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling.
    - `resolvedInput` object, required — Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options.
      - `ratio` string, required — Concrete output ratio derived from aspectRatio and resolution for the selected model.
      - `aspectRatio` string, required — Aspect ratio used for routing display.
      - `resolution` string, required — Megapixel tier used for routing display.
    - `estimatedCost` object, required — Estimated cost, computed against current pricing.
      - `credits` number, required — Estimated cost of the generation in credits.
    - `capacityFallback` object — Present only when the config enables fallback.onCapacity and capacity affected this request.
      - `skipped` string[], required — Eligible models that were considered for this request but not selected because this account is at its concurrency limit for them.
      - `allExhausted` boolean, required — True when every eligible model was at its concurrency limit, so the best-ranked model was used and the task will queue.

## Other responses

- `400` — Error
- `404` — The referenced router config does not exist or is not accessible to this account.
- `429` — You have exceeded the rate limit for this endpoint.

---

[API](https://skmtc.net/runwayml/apis/runwayml-api.md) · [All operations](https://skmtc.net/runwayml/apis/runwayml-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runwayml/runwayml-api/revisions/cbbe796a13a0/schema)