---
title: "ImageGenerationRequest"
---

Image generation request input


## Fields

| Field                                                                                                                                                                                                                                                                                                                                                                                                  | Type                                                                                                                                                                                                                                                                                                                                                                                                   | Required                                                                                                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                            | Example                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aspect_ratio`                                                                                                                                                                                                                                                                                                                                                                                         | [Optional[components.ImageGenerationRequestAspectRatio]](../components/imagegenerationrequestaspectratio.mdx)                                                                                                                                                                                                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Normalized aspect ratio of the generated image. Providers clamp to their supported subset.                                                                                                                                                                                                                                                                                                             | 16:9                                                                                                                                                                                                                                                                                                                                                                                                   |
| `background`                                                                                                                                                                                                                                                                                                                                                                                           | [Optional[components.ImageGenerationRequestBackground]](../components/imagegenerationrequestbackground.mdx)                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Background treatment. `transparent` requires an output_format that supports alpha (png or webp).                                                                                                                                                                                                                                                                                                       | auto                                                                                                                                                                                                                                                                                                                                                                                                   |
| `input_references`                                                                                                                                                                                                                                                                                                                                                                                     | List[[components.ContentPartImage](../components/contentpartimage.mdx)]                                                                                                                                                                                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs.                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                        |
| `model`                                                                                                                                                                                                                                                                                                                                                                                                | *str*                                                                                                                                                                                                                                                                                                                                                                                                  | :heavy_check_mark:                                                                                                                                                                                                                                                                                                                                                                                     | The image generation model to use                                                                                                                                                                                                                                                                                                                                                                      | bytedance-seed/seedream-4.5                                                                                                                                                                                                                                                                                                                                                                            |
| `n`                                                                                                                                                                                                                                                                                                                                                                                                    | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Number of images to generate (1-10). Providers that only support single-image generation reject n > 1.                                                                                                                                                                                                                                                                                                 | 1                                                                                                                                                                                                                                                                                                                                                                                                      |
| `output_compression`                                                                                                                                                                                                                                                                                                                                                                                   | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob.                                                                                                                                                                                                                                                                                           | 100                                                                                                                                                                                                                                                                                                                                                                                                    |
| `output_format`                                                                                                                                                                                                                                                                                                                                                                                        | [Optional[components.ImageGenerationRequestOutputFormat]](../components/imagegenerationrequestoutputformat.mdx)                                                                                                                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | 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`.                                                                                                                                                                                             | png                                                                                                                                                                                                                                                                                                                                                                                                    |
| `prompt`                                                                                                                                                                                                                                                                                                                                                                                               | *str*                                                                                                                                                                                                                                                                                                                                                                                                  | :heavy_check_mark:                                                                                                                                                                                                                                                                                                                                                                                     | Text description of the desired image                                                                                                                                                                                                                                                                                                                                                                  | a red panda astronaut floating in space, studio lighting                                                                                                                                                                                                                                                                                                                                               |
| `provider`                                                                                                                                                                                                                                                                                                                                                                                             | [Optional[components.ImageGenerationRequestProvider]](../components/imagegenerationrequestprovider.mdx)                                                                                                                                                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Provider-specific passthrough configuration                                                                                                                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                        |
| `quality`                                                                                                                                                                                                                                                                                                                                                                                              | [Optional[components.ImageGenerationRequestQuality]](../components/imagegenerationrequestquality.mdx)                                                                                                                                                                                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Rendering quality. Providers without a quality knob ignore this.                                                                                                                                                                                                                                                                                                                                       | high                                                                                                                                                                                                                                                                                                                                                                                                   |
| `resolution`                                                                                                                                                                                                                                                                                                                                                                                           | [Optional[components.ImageGenerationRequestResolution]](../components/imagegenerationrequestresolution.mdx)                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider.                                                                                                                                                                                                                                                                                                 | 2K                                                                                                                                                                                                                                                                                                                                                                                                     |
| `seed`                                                                                                                                                                                                                                                                                                                                                                                                 | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | 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.                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                        |
| `size`                                                                                                                                                                                                                                                                                                                                                                                                 | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | 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. | 2K                                                                                                                                                                                                                                                                                                                                                                                                     |
| `stream`                                                                                                                                                                                                                                                                                                                                                                                               | *Optional[bool]*                                                                                                                                                                                                                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                     | 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.                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                        |