v1 images

Generate Images

Dedicated image generation endpoint using the Universal Schema with flat parameters.

**Universal Base Schema:**
- user_id (str, required): The end-user ID
- project_id (str, required): The project ID
- persona_id (str, optional): The specific system persona/voice to use
- disabled_learning (bool, optional): If true, request is ignored by long-term memory
- use_reasoning (bool, optional): Enable reasoning loop for constraint-satisfying generation

**Input:**
- text_input (str, optional): The prompt/description for image generation
- session_id (str, optional): Session ID for conversation context

**Reference inputs:**
- image_base64 (str, optional): Base64 encoded reference image for context
- video_base64 (str, optional): Base64 encoded reference video for context
- audio_base64 (str, optional): Base64 encoded reference audio for context

**Image Params (Flat):**
- model (str, optional): Model ID (default: gemini-3.1-flash). Available image models: gemini-3.1-flash, gemini-3-flash, gemini-3.1-pro
- aspect_ratio (str, optional): Aspect ratio, e.g. "1:1", "16:9", "9:16" (default: 1:1).
- resolution (str, optional): Resolution tier: "1K", "2K", or "4K" (default: 4K).
- seed (int, optional): Random seed for reproducibility

**Authentication**: Requires valid API key or JWT token

post/v1/images/generations

Request body

user_idstring required

The end-user ID

project_idstring nullable

The project ID

persona_idstring nullable

The specific system persona/voice to use

disabled_learningboolean

If true, this request is ignored by long-term memory

use_reasoningboolean

Enable Chain-of-Thought/Reasoning steps before generation

max_reasoning_iterationsinteger

Max reasoning steps if reasoning is enabled

text_inputstring required

The prompt/description for image generation

session_idstring nullable

Session ID for conversation context

image_base64string nullable

Base64 encoded reference image for context

video_base64string nullable

Base64 encoded reference video for context

audio_base64string nullable

Base64 encoded reference audio for context

modelstring

Image generation model ID

aspect_ratiostring

Aspect ratio for the generated image, e.g. '1:1', '16:9', '9:16', '4:3', '3:4'.

resolution'1K' | '2K' | '4K'

Resolution tier for the generated image: '1K', '2K', or '4K'.

seedinteger nullable

Random seed for reproducibility

temperaturenumber nullable

Temperature for retrieval LLM calls (0.0-2.0). Lower = more deterministic.

Example request

{
  "aspect_ratio": "1:1",
  "model": "gemini-3.1-flash",
  "project_id": "proj_ABC",
  "resolution": "2K",
  "seed": 12345,
  "text_input": "A golden retriever in a space suit",
  "use_reasoning": false,
  "user_id": "user_123"
}

Response

Successful Response

image_base64string nullable

Base64 encoded image. Present when the payload is under ~30 MB. May be absent for very large outputs.

image_urlstring nullable

Signed GCS URL to download the image (expires after 24 h). Always present when the upload succeeds.

output_typestring

Delivery method: 'both' (base64 + url), 'url' (url only, base64 omitted due to size), or 'base64' (GCS upload failed).

image_formatstring

Image format, e.g. png, jpeg, webp

successboolean

Whether the request succeeded

Changes

Changed in 6 of the 29 revisions of this API.4112

Mar 18, 2026af32b402b5fc1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Mar 5, 20268c335444d304216See the full diff
- ▲
  request property was restricted to a list of enum values
  request-property-became-enum
- ▲
  request property list-of-types was narrowed by removing types null from media type application/json
  request-property-list-of-types-narrowed
- ●
  removed the request property
  request-property-removed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new 1K enum value to the request property
  request-property-enum-value-added
- ○
  added the new 2K enum value to the request property
  request-property-enum-value-added
- ○
  added the new 4K enum value to the request property
  request-property-enum-value-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  the response's property default value changed from base64 to both for the status
  response-property-default-value-changed
Feb 26, 2026cc740030b11e1See the full diff
- ○
  the request property default value changed from gemini-3-flash to gemini-3.1-flash
  request-property-default-value-changed
Feb 25, 20269cc8f20f40c822See the full diff
- ▲
  the response property became optional for the status
  response-property-became-optional
- ▲
  response property image_base64 list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
Feb 21, 20266e8acd7c094d1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Feb 9, 2026bb6f89ac9cd31See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 20 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history