---
title: "Generate an image"
method: POST
path: "/v1/images/generations"
---

# Generate an image

`POST /v1/images/generations`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/v1/images/generations`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Compatible with the OpenAI Images protocol. Text-to-image when no image is provided; image editing when an image is provided.

## Request body

- ImageGenerationRequest: Shared parameters for the Image Generation API. Text-to-image when no image is provided; image editing when an image is provided. Parameters marked (GPT only) or (Gemini only) apply only to those model families; unsupported parameters are ignored.
  - `model` 'openai/gpt-image-2.5-flare' | 'openai/gpt-image-2.5-sunburst' | 'openai/gpt-image-2' | 'openai/gpt-image-1-mini' | 'google/gemini-3-pro-image' | 'google/gemini-3.1-flash-image', required: The model to use. Aliases `nano-banana-pro` (= `google/gemini-3-pro-image`) and `nano-banana-2` (= `google/gemini-3.1-flash-image`) are also accepted.
  - `prompt` string, required: The text description for the model. The length limit is set by the model.
  - `n` integer: (GPT only) Number of images to generate. For Gemini, request multiple images in the `prompt` instead.
  - `size` string: Output size as `width x height` (e.g. `1024x1024`) or `auto`.
  - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto': (GPT only) Generation quality.
  - `background` 'transparent' | 'opaque' | 'auto': (GPT only) Background setting.
  - `output_format` 'png' | 'jpeg' | 'webp': Output image format. GPT supports png/jpeg/webp; Gemini supports png/jpeg (webp falls back to png).
  - `output_compression` integer: (GPT only) Compression level (percent). Effective only when `output_format` is jpeg or webp.
  - `moderation` 'low' | 'auto': (GPT only) Content moderation strength.
  - `thinking_level` 'minimal' | 'high': (Gemini only) Thinking effort before generation.
  - `response_modalities` string[]: (Gemini only) Controls returned modalities. `["text","image"]` returns the image plus accompanying text; `["image"]` returns only the image.
  - `media_resolution` 'low' | 'medium' | 'high': (Gemini only) Processing resolution for input reference images.
  - `response_format` 'b64_json': Return format.
  - `stream` boolean: (GPT only) Whether to stream the response.
  - `partial_images` integer: (GPT only) Number of intermediate preview images to stream. Effective only when `stream=true`. Each preview costs an extra 100 image output tokens.
  - `user` string: A unique identifier for the end user. Use hashed or pseudonymous identifiers to avoid passing personally identifiable information.
  - `image` union: Reference/source image(s) for editing, a data URL prefix or a raw base64 string. Providing an image enters edit mode. An array passes multiple reference images.
    - string
    - string[]
  - `mask` string: (GPT only) Mask image, base64-encoded PNG matching the input size. Transparent areas are repainted. Effective only when `image` is provided.

## Response `200`

Successful image response. When `stream=false`, returns a single object. When `stream=true` (GPT only), returns an SSE stream of `image_generation.partial_image` / `image_edit.partial_image` preview events followed by a `image_generation.completed` / `image_edit.completed` event.

- union
  - ImageGenerationResponse: A non-streaming image response. Images are always returned as base64.
    - `id` string, required: The unique identifier for this request.
    - `created` integer, required: Unix timestamp (in seconds) of when the request was created.
    - `background` 'transparent' | 'opaque': (GPT only) The background setting actually applied.
    - `output_format` 'png' | 'jpeg' | 'webp': The output format actually applied; for Gemini, derived from the mimeType.
    - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max': (GPT only) The quality tier actually applied.
    - `size` string: (GPT only) The output size actually applied; useful when `size` was `auto`.
    - `data` object[], required: The generated images, one element per image.
      - `b64_json` string: Base64-encoded image content.
    - `text` string: (Gemini only) Plain-text summary of text the model produced alongside the image. For exact interleaving, read `parts`.
    - `parts` ImagePart[]: (Gemini only) Content parts in the model's original order, preserving text/image interleaving.
      - `type` 'text' | 'image': The part type.
      - `text` string: Text content. Present when `type` is `text`.
      - `index` integer: Index into the `data` array. Present when `type` is `image`; read the image bytes from `data[index].b64_json`.
    - `usage` ImageUsage, required: Token usage information.
      - `input_tokens` integer, required: Input tokens (text prompt + input image tokens).
      - `input_tokens_details` object
        - `text_tokens` integer: Text tokens of the prompt.
        - `image_tokens` integer: Tokens of the input images.
      - `output_tokens` integer, required: Output tokens (generated image tokens + reasoning text tokens).
      - `output_tokens_details` object
        - `text_tokens` integer: Output tokens used by reasoning text.
        - `image_tokens` integer: Tokens of the generated images.
      - `total_tokens` integer, required: Total tokens (input_tokens + output_tokens).
  - ImageGenerationStreamEvent: A streaming SSE event. Partial preview images arrive first (each with `partial_image_index`), then one `completed` event with `usage`. The event type prefix is `image_generation` for text-to-image and `image_edit` for editing.
    - `id` string, required: Request identifier. Identical across all events of one request.
    - `type` 'image_generation.partial_image' | 'image_generation.completed' | 'image_edit.partial_image' | 'image_edit.completed', required: The event type.
    - `b64_json` string, required: Base64 image for this event: the current preview for `partial_image`, the final image for `completed`.
    - `created_at` integer: Unix timestamp when the event was generated.
    - `size` string: (GPT only) The output size actually applied; useful when `size` was `auto`.
    - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max': (GPT only) The quality tier actually applied.
    - `background` 'transparent' | 'opaque': (GPT only) The background setting actually applied.
    - `output_format` 'png' | 'jpeg' | 'webp': The output format actually applied; for Gemini, derived from the mimeType.
    - `partial_image_index` integer: Present only in `partial_image` events. Preview index, starting at 0.
    - `usage` ImageUsage: Token usage information.
      - `input_tokens` integer, required: Input tokens (text prompt + input image tokens).
      - `input_tokens_details` object
        - `text_tokens` integer: Text tokens of the prompt.
        - `image_tokens` integer: Tokens of the input images.
      - `output_tokens` integer, required: Output tokens (generated image tokens + reasoning text tokens).
      - `output_tokens_details` object
        - `text_tokens` integer: Output tokens used by reasoning text.
        - `image_tokens` integer: Tokens of the generated images.
      - `total_tokens` integer, required: Total tokens (input_tokens + output_tokens).

## Other responses

- `400`: Missing or invalid parameter
- `401`: Invalid API Key
- `403`: Insufficient balance in account
- `404`: Model or resource not found
- `429`: Exceeding the rate limit
- `500`: Internal error

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)