Sign in

v29

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-233765161.7 KB
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