Images

Generate an image

Generates an image from a text prompt via the image generation router

post/images

Request body

aspect_ratio'1:1' | '1:2' | '1:4' | '1:8' | '2:1' | '2:3' | '2.35:1' | '3:2' | '3:4' | '4:1' | '4:3' | '4:5' | '5:2' | '5:4' | '5:7' | '7:5' | '8:1' | '9:16' | '16:9' | '9:19.5' | '19.5:9' | '9:20' | '20:9' | '9:21' | '21:9' | 'auto'

Normalized aspect ratio of the generated image. Providers clamp to their supported subset.

background'auto' | 'transparent' | 'opaque'

Background treatment. transparent requires an output_format that supports alpha (png or webp).

modelstring required

The image generation model to use

ninteger

Upper bound on the number of images to generate (1-10). Providers may return fewer images, and providers that only support single-image generation reject n > 1.

output_compressioninteger

Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob.

output_format'png' | 'jpeg' | 'webp' | 'svg'

Encoding of the returned image bytes. Most models produce raster formats (png, jpeg, webp). SVG is supported by vectorization models (e.g. Quiver) — the SVG markup is UTF-8 base64-encoded in b64_json.

promptstring required

Text description of the desired image

Rendering quality. Providers without a quality knob ignore this.

resolution'512' | '768' | '1K' | '2K' | '4K'

Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider.

seedinteger

If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers.

session_idstring

A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.

sizestring

Optional. A convenience shorthand for output dimensions — pass a tier ("2K", "4K") or explicit pixels ("2048x2048") and we normalize it to the right dimensions for the chosen provider. A tier size is equivalent to setting resolution and combines with aspect_ratio. An explicit pixel size is authoritative: a mismatched resolution or aspect_ratio alongside it is rejected with a 400.

streamboolean

If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response.

userstring

A stable identifier for your end-users. Used to help detect and prevent abuse. Never sent to providers verbatim: for providers whose data policy requires user IDs, it is folded into a hashed, per-account upstream user identifier.

Example request

{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "a red panda astronaut floating in space, studio lighting"
}

Response

Image generation response

createdinteger required

Unix timestamp (seconds) when the image was generated

Example response

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>"
    }
  ],
  "usage": {
    "completion_tokens": 4175,
    "cost": 0.04,
    "prompt_tokens": 0,
    "total_tokens": 4175
  }
}

Changes

Changed in 47 of the 303 revisions of this API.1333120

Sep 25, 202631b1cd25caca4See the full diff
- ○
  added the new optional request property //////
  new-optional-request-property
- ○
  added the new Respan enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new Respan enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new Respan enum value to the request property //////
  request-property-enum-value-added
Sep 25, 202607eab76402e73See the full diff
- ○
  added the new 5:7 enum value to the request property
  request-property-enum-value-added
- ○
  added the new 768 enum value to the request property
  request-property-enum-value-added
- ○
  added the new 7:5 enum value to the request property
  request-property-enum-value-added
Sep 24, 20264c8b9dc76c454See the full diff
- ○
  added the new optional request property //////
  new-optional-request-property
- ○
  added the new ScaleDown enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new ScaleDown enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new ScaleDown enum value to the request property //////
  request-property-enum-value-added
Sep 17, 20263066544509b54See the full diff
- ○
  added the new optional request property //////
  new-optional-request-property
- ○
  added the new Unbiased enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new Unbiased enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new Unbiased enum value to the request property //////
  request-property-enum-value-added
Sep 17, 20262de027b6dfcd4See the full diff
- ○
  added the new optional request property //////
  new-optional-request-property
- ○
  added the new TypeSafe enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new TypeSafe enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new TypeSafe enum value to the request property //////
  request-property-enum-value-added
Sep 16, 202698e12733cd621See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Sep 15, 202681e9c582ae1c1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Sep 15, 2026407c2ddfad8c1See the full diff
- ●
  the request property's maxLength was set to 256
  request-property-max-length-set
Sep 15, 2026747e43d988682See the full diff
- ○
  added the new 2.35:1 enum value to the request property
  request-property-enum-value-added
- ○
  added the new 5:2 enum value to the request property
  request-property-enum-value-added
Sep 14, 202654ab2e9ba8574See the full diff
- ○
  added the new optional request property //////
  new-optional-request-property
- ○
  added the new AssemblyAI enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new AssemblyAI enum value to the request property //////
  request-property-enum-value-added
- ○
  added the new AssemblyAI enum value to the request property //////
  request-property-enum-value-added

Full history (47 revisions)