Create image

POST/v1/images/generations

Create an image from text, or create/edit an image from text plus one or more input images. Image generation responses are returned directly from this request; unlike video generation, there is no submit-and-poll task flow. Use the returned data[].url to download the image directly. To use the dedicated image download or delete endpoints, first retrieve the image record ID from GET /v1/images.

Authentication

Authorization Bearer

API key as bearer token in Authorization header.

Request Body

modelstringrequired

Model ID.

promptstringrequired

Image generation prompt.

ninteger

Number of images to generate.

sizestring

Requested output image dimensions, such as width-by-height, when the model uses explicit image size values.

aspect_ratiostring

Requested output image shape as a width-to-height ratio.

resolutionstring

Requested output image resolution or resolution tier.

qualitystring

Requested generation quality or fidelity tier.

seedinteger

Optional numeric seed for repeatable generation when deterministic seeding is supported.

prompt_extendboolean

Prompt extension flag.

negative_promptstring

Negative prompt.

watermarkboolean

Controls whether generated images include a watermark when supported.

response_formatstring

Response format.

imagesarray

Reference images.

sequential_image_generationstring

Sequential image generation mode.

sequential_image_generation_optionsobject

Sequential image generation configuration.

sequential_image_generation_options.max_imagesinteger

Maximum number of images to generate in sequential mode.

optimize_prompt_optionsobject

Prompt optimization configuration.

optimize_prompt_options.modestring

Prompt optimization mode, such as standard or fast.

strengthnumber

Input image influence strength.

enable_interleaveboolean

Interleaved generation flag.

enable_web_searchboolean

Web search flag.

output_formatstring

Requested file format for generated image outputs.

streamboolean

Streaming response flag.

metadataobject

Application metadata.

extra_bodyobject

Additional request body fields.

provider_optionsobject

Upstream configuration.

moderationstring

Content moderation strictness for generated images.

partial_imagesinteger

Number of partial images emitted before the final image in streaming mode

maskstring

Optional mask image for image edits. Transparent areas indicate where the input image may be edited.

bbox_listarray

Per-input-image bounding boxes for interactive image editing.

enable_sequentialboolean

Enables sequential image-set generation when supported by the model.

thinking_modeboolean

Enables publisher thinking mode for image generation.

color_palettearray

Custom output color palette entries with publisher-defined colors and ratios.

backgroundstring

Background handling for generated images, such as auto, transparent, or opaque.

layer_decompositionboolean

Whether the publisher should decompose the generated image into editable layers.

output_compressioninteger

Output image compression percentage for formats that support compression.

input_fidelitystring

How closely an image edit should preserve details from the input images.

userstring

Stable end-user identifier forwarded to publishers that accept it.

thinking_levelstring

Publisher thinking level used while generating an image.

include_thoughtsboolean

Whether the publisher should include thought summaries in the response.

enable_image_searchboolean

Whether Google Search grounding may use image search results.

media_resolutionstring

Publisher media-resolution tier used when processing input media.

Response

createdinteger

Unix timestamp.

modelstring

Model identifier that served the request.

dataobject[]

Generated images.

data.urlstring

URL to download the generated image.

data.b64_jsonstring

Base64-encoded image when returned by the model.

data.output_formatstring

Output image format when returned by the model, for example jpeg or png.

data.sizestring

Output image dimensions when returned by the model, in <width>x<height> format.

data.errorobject | null

Per-image error details for failed image generations.

usageobject

Usage stats for the request. The usage structure varies by model. All fields below are optional and appear only when returned by the selected model.

usage.generated_imagesinteger

Number of images successfully generated by the model.

usage.input_imagesinteger

Number of input reference images.

usage.prompt_tokensinteger

Input token count used by models with OpenAI Chat-style naming.

usage.completion_tokensinteger

Output token count used by models with OpenAI Chat-style naming.

usage.input_tokensinteger

Input tokens consumed by the request.

usage.output_tokensinteger

Output tokens consumed by the request.

usage.total_tokensinteger

Total tokens consumed by the request.

usage.input_tokens_detailsobject

Input token counts by modality.

usage.output_tokens_detailsobject

Output token counts by modality.

usage.output_text_tokensinteger

Flattened text output token count.

usage.output_image_tokensinteger

Flattened image output token count.

usage.generated_images_countinteger

Compatibility field for the generated image count.

usage.image_countinteger

Compatibility field for the generated image count.

usage.resolutionstring

Actual output resolution tier used for generation or metering.

usage.cache_read_tokensinteger

Input tokens read from cache.

usage.search_queries_countinteger

Search queries used during generation.

errorobject

Request-level error details when an error payload is returned.

error.codestring

Error code.

error.messagestring

Error message.

Request

1curl -X POST https://api.token360.ai/v1/images/generations \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "nano-banana-pro",
6    "prompt": "A minimalist sunrise over calm water, digital illustration",
7    "size": "1024x1024",
8    "aspect_ratio": "1:1"
9  }'

Response

The usage below is a snapshot from one real request and only illustrates the response shape. Fields and values vary by model, input content, image count, resolution, and the model version that serves the request.

JSON

1{
2  "created": 1789126936,
3  "model": "gemini-3-pro-image",
4  "data": [
5    {
6      "url": "your-generated-image-url",
7      "output_format": "png",
8      "size": "1k"
9    }
10  ],
11  "usage": {
12    "completion_tokens": 1304,
13    "generated_images": 1,
14    "generated_images_count": 1,
15    "image_count": 1,
16    "input_tokens": 9,
17    "input_tokens_details": {
18      "text_tokens": 9
19    },
20    "output_image_tokens": 1120,
21    "output_text_tokens": 184,
22    "output_tokens": 1304,
23    "output_tokens_details": {
24      "image_tokens": 1120,
25      "text_tokens": 184
26    },
27    "prompt_tokens": 9,
28    "resolution": "1k",
29    "search_queries_count": 0,
30    "total_tokens": 1313
31  }
32}

Was this page helpful?