> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/api-reference/endpoints/image-generation.md). # Image Generation Asynchronous endpoint: `POST /api/v1/image/generations/async` Poll asynchronous job: `GET /api/v1/image/generations/async/:generationId` ### Request Fields | Field | Type | Required | Validation | Description | | ---------------------------- | --------- | -------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | Yes | String | User-facing model identifier from `/ai/models`. | | `content` | object\[] | Yes | Non-empty array | Ordered request content. Supports text and image inputs. | | `size` | string | No | Must match `x` with positive integers, for example `1024x1024` | Requested output image size. Providers may translate this into their own aspect-ratio or size tiers. | | `numberOfImages` | integer | No | Minimum `1`, maximum `15` | Expected number of output images. Also state the desired number of pictures in the text prompt because some models can return fewer images than requested. Actual generated count varies by model and provider. BytePlus multi-image models cap total images at `15`, counting both reference images and expected output images. | | `guidanceScale` | number | No | Minimum `1`, maximum `10` | Prompt adherence versus creative freedom. Higher values follow the prompt more closely. This is not universal: the current adapter forwards it to BytePlus image models, and BytePlus support is model-specific. Unsupported models may ignore or reject it. | | `outputFormat` | string | No | `png`, `jpeg`, or `webp` | Requested output file format. `webp` is for OpenAI gpt-image (Ofox `openai/*`); BytePlus image models accept `png`/`jpeg` only. Provider/model support is narrower than the DTO, and unsupported models may ignore or reject the value. | | `quality` | string | No | `auto`, `high`, `medium`, or `low` | Rendering quality. OpenAI gpt-image only (Ofox `openai/*`); ignored for other providers/models. Higher quality costs more. | | `background` | string | No | `transparent`, `opaque`, or `auto` | Background transparency. OpenAI gpt-image only (Ofox `openai/*`). `transparent` requires `outputFormat` of `png` or `webp`. | | `outputCompression` | integer | No | Minimum `0`, maximum `100` | Compression level for `webp`/`jpeg` output. OpenAI gpt-image only (Ofox `openai/*`). | | `responseFormat` | string | No | `url` or `b64_json` | Requested provider return shape: `url` asks for a provider URL, `b64_json` asks for inline base64. This is not supported by every provider/model; the current adapter forwards it to BytePlus image models only. | | `watermark` | boolean | No | Boolean | Whether to add an "AI generated" watermark when supported. | | `optimizePromptOptions` | object | No | Object | BytePlus-only prompt optimization controls. Currently supports `mode`; other current image adapters do not forward this field. | | `optimizePromptOptions.mode` | string | No | `standard` or `fast` | BytePlus prompt optimization mode. `standard` favors quality; `fast` favors lower latency where supported by the selected BytePlus model. | | `maxTokens` | integer | No | Minimum `1` | Maximum tokens to generate for providers that accept token controls in image generation. Some image models do not support this field; BytePlus image generation strips it before sending the provider request, while OpenRouter image generation forwards it. | ### Image Content Parts All content parts require a `type` discriminator. | Type | Fields | Description | | ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `text` | `text: string` | Prompt text. Multiple text parts are joined by providers that require a single prompt. | | `imageUrl` | `url: string` | Publicly fetchable image URL. Must pass URL validation. | | `imageBase64` | `data: string`, `mediaType?: string` | Raw base64 image bytes or a full data URL. `mediaType` is required for raw base64 and must be one of the supported image MIME types. | Supported image MIME types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`, `image/tiff`, `image/heic`, `image/heif`, `image/avif`. ### Request Example ```json { "model": "seedream-4-0", "content": [ { "type": "text", "text": "Create two clean product mockup images on a neutral background." } ], "size": "1024x1024", "numberOfImages": 2, "responseFormat": "url", "watermark": false } ``` ### ImageResult Fields | Field | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `images` | object\[] | Yes | Generated image outputs. | | `images[].url` | string | No | Provider URL for the generated image when returned as a URL. Provider URLs can expire. | | `images[].downloadUrl` | string | No | Presigned R2 download link for the archived output. This URL expires; re-fetch instead of storing it permanently. | | `images[].b64` | string | No | Base64-encoded generated image bytes. | | `images[].assetId` | string | No | Asset id of the archived image. Reuse via `imageAssetId` in later requests. | | `usage` | object | No | Provider-reported usage. | | `usage.generatedImages` | number | No | Number of images counted by the provider. | | `usage.totalTokens` | number | No | Total tokens consumed when reported. | | `usage.inputTokens` | number | No | Text plus image input tokens when reported. | | `usage.outputTokens` | number | No | Text plus image output tokens when reported. | | `usage.inputImageTokens` | number | No | Subset of input tokens attributed to image input. | | `usage.outputImageTokens` | number | No | Subset of output tokens attributed to generated image output. | | `usage.usdCost` | number | No | Provider-reported USD cost when the provider reports a billing figure. | ### Async Image Status Fields | Field | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------------------------- | | `status` | string | Yes | Current job status: `queued`, `processing`, `succeeded`, or `failed`. | | `generationId` | string | Yes | Generation id returned when the async job was accepted. | | `result` | object | No | `ImageResult`, present after success. | | `error` | string | No | Failure message when `status` is `failed`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avis.xyz/api-reference/endpoints/image-generation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.