---
title: "Create image"
method: POST
path: "/v1/images/generations"
tags: ["Images"]
---

# Create image

`POST /v1/images/generations`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/images/generations`
- Auth: HTTP bearer

Creates an image given a prompt.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- ImageGenerationRequest
  - `prompt` string: Image description. Required for every model that takes a prompt; a tool whose contract lists no prompt (background removal, upscaling, vectorizing) is called without one.
  - `model` string, required: Model to use. Send this explicitly; query GET /v1/models?recommended_for=image for current recommendations.
  - `operation` 'text-to-image' | 'image-to-image' | 'image-edit': Public image operation family. Reference-image models use image-to-image with image_url, image_urls, or reference_image_urls.
  - `image_url` string, uri: Single reference image URL for compatible image-to-image models.
  - `image_urls` string[]: Reference image URLs for compatible image-to-image models.
  - `reference_image_urls` string[]: Alias used by compatible reference-image model families.
  - `mask_url` string, uri: Optional mask URL for compatible image operations.
  - `n` integer: Number of images to generate
  - `size` string: Image size. Defaults are model-specific. For gpt-image-2, omit this field or use auto for automatic sizing, or send WIDTHxHEIGHT; custom dimensions must both be multiples of 16, longest edge <= 3840px, long/short ratio <= 3:1, and total pixels between 655,360 and 8,294,400. For Google image models with resolution tiers (gemini-3.1-flash-image, gemini-3-pro-image, gemini-3.1-flash-lite-image, gemini-nano-banana-2.1, nano-banana-2, nano-banana-2.1, nano-banana-pro), send an output size from the model's size table or a resolution tier: 1K, 2K, or 4K. TokenLab sends a tier as resolution. A tier that the model does not support, or a tier that is different from resolution, returns 400 invalid_image_size_contract. The recommended form for these models is aspect_ratio with resolution.
  - `quality` string: Image quality. Defaults and accepted values are model-specific. For gpt-image-2, omit this field or use auto for automatic quality, or send low, medium, or high. Other models may accept different values; check the model details.
  - `style` 'vivid' | 'natural': Optional model-specific style selector. Only send when the selected model documents support for this parameter.
  - `expand_prompt` boolean: Ask compatible models to expand or enhance the prompt.
  - `prompt_extend` boolean: For z-image-turbo, enable prompt expansion. Defaults to false. Enabling it uses the model's prompt-expansion price.
  - `negative_prompt` string: Content to avoid for compatible image models.
  - `seed` integer: Seed for deterministic-compatible image models.
  - `response_format` 'url' | 'b64_json': How the images are returned. Omitted: when the model returns image bytes, each image is in data[].b64_json, and also in data[].url when TokenLab stored it; when the model returns a link, each image is in data[].url. url: only data[].url. b64_json: only data[].b64_json. Links are TokenLab media-result URLs that stay valid for 30 days.
  - `async` boolean: Return a task before the final image is ready when the selected model supports public async execution.
  - `background` 'transparent' | 'opaque' | 'auto': Background handling for compatible image flows. For gpt-image-2 generation and edits, accepted values are auto and opaque; transparent is not supported. Other models may support different values.
  - `output_format` 'png' | 'jpeg' | 'webp': Output image format for compatible image models such as gpt-image-2
  - `output_compression` integer: Output compression level from 0 to 100 for compressed formats
  - `compression` integer: Alias for output_compression when supported by the selected model
  - `moderation` 'auto' | 'low': Moderation strictness for compatible image models such as gpt-image-2
  - `stream` boolean: Reserved image streaming flag. The public generation route currently rejects true.
  - `aspect_ratio` string: Aspect-ratio selector for compatible image model families.
  - `resolution` string: Resolution selector for compatible image model families.
  - `user` string: End-user identifier

## Response `200`

Successful response

- ImageGenerationResponse
  - `created` integer, required: Unix timestamp
  - `data` object[], required
    - `url` string: Image URL
    - `b64_json` string: Base64 encoded image
    - `revised_prompt` string: Revised prompt returned by models that rewrite or enhance the submitted prompt.
  - `task_id` string: Task ID when the request runs as a task.
  - `status` string: Task status when the request runs as a task.
  - `poll_url` string: URL to poll for the task result.
  - `error` union: Why the task failed: a string, or an object with `message` and, when known, `type`, `code`, `param` and `retryable`.
    - string
    - object
      - `message` string, required
      - `type` string
      - `code` string
      - `param` string
      - `retryable` boolean
  - `error_details` AsyncTaskErrorDetails: Why a task failed. A status read returns HTTP 200 even for a failed task; `status` here is the status of the failure itself.
    - `projection_version` integer: `2` means `message` is the final reason for the failure.
    - `status` integer, required
    - `message` string, required
    - `type` string, required
    - `code` string, required
    - `param` string: The request field at fault, omitted when no specific field is known.
    - `retryable` boolean, required
    - `upstream` AsyncTaskUpstreamError: The upstream service's own error, present only for a task that ran on an Official route. Its `code` values are defined by the upstream service and may change; branch on `error_details.code` and `error_details.type`.
      - `source` string: Upstream service name, when known.
      - `code` string
      - `message` string, required
      - `param` string
  - `media_retention` MediaRetention: Saving status of the media results in this response. Present when the status is known within the response time limit; when it is absent, the media URLs still work.
    - `days` integer, required: Days a media-result URL stays valid after the result is first recorded.
    - `items` object[], required
      - `url` string, uri, required
      - `kind` 'image' | 'video' | 'audio' | '3d', required
      - `content_type` string
      - `status` 'saving' | 'saved' | 'failed' | 'expired', required
      - `expires_at` string, date-time, required

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment Required - Insufficient balance or quota exceeded
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)