Image Generation - /v1/images/generations

Endpoint

POST http://127.0.0.1:8045/v1/images/generations

Generate images using Google’s Imagen 3 engine through an OpenAI-compatible interface. Supports custom sizes, quality levels, and aspect ratios.

Authentication

string

required

Bearer token authentication

Authorization: Bearer sk-antigravity

Request Headers

string

required

Must be application/json

Request Body

string

required

Image model identifier:

gemini-3-pro-image - Standard image generation
gemini-3.1-flash-image - Fast image generation
gemini-3-pro-image-16-9-4k - With aspect ratio and quality suffix

string

required

Text description of the image to generate

Be descriptive! Include style, mood, composition, and details for best results.

string

Image size in WIDTHxHEIGHT format or aspect ratio:

Exact dimensions: 1920x1080, 1024x1024, 1280x720
Aspect ratios: 16:9, 9:16, 4:3, 3:4, 21:9, 1:1

Auto-calculates aspect ratio from exact dimensions.Default: 1024x1024 (1:1 aspect ratio)

string

Image quality level:

hd - 4K resolution (highest quality)
medium - 2K resolution
standard - Default resolution (1K)

Default: standard

string

Direct Gemini native resolution parameter (takes precedence over quality):

4K - 4096px maximum dimension
2K - 2048px maximum dimension
1K - 1024px maximum dimension

imageSize has higher priority than quality. If both are set, imageSize is used.

integer

Number of images to generate (1-10)Default: 1

string

Response format:

b64_json - Base64-encoded JSON (recommended)
url - Data URI format

Default: url

string

Person generation policy:

allow - Allow person generation
deny - Block person generation

Default: allow

Response Format

integer

Unix timestamp of generation

array

Array of generated images

Show Image Object

string

Data URI (if response_format is url)

data:image/png;base64,iVBORw0KG...

string

Base64-encoded image data (if response_format is b64_json)

string

Enhanced/revised prompt used for generation (if applicable)

Example: Basic Generation

curl -X POST http://127.0.0.1:8045/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-antigravity" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "一座未来主义风格的城市,赛博朋克,霓虹灯",
    "size": "1920x1080",
    "quality": "hd",
    "n": 1,
    "response_format": "b64_json"
  }'

Example: Python SDK

import openai
import base64

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

# Generate image
response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="一座未来主义风格的城市,赛博朋克,霓虹灯",
    size="1920x1080",
    quality="hd",
    n=1,
    response_format="b64_json"
)

# Save image
image_data = base64.b64decode(response.data[0].b64_json)
with open("output.png", "wb") as f:
    f.write(image_data)

print("Image saved to output.png")

Example: Multiple Sizes

import openai

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

# Generate multiple aspect ratios
sizes = ["1920x1080", "1024x1024", "1080x1920"]
prompt = "A serene mountain landscape at sunset"

for size in sizes:
    response = client.images.generate(
        model="gemini-3-pro-image",
        prompt=prompt,
        size=size,
        quality="hd"
    )
    
    # Save with size in filename
    import base64
    img_data = base64.b64decode(response.data[0].b64_json)
    with open(f"landscape_{size}.png", "wb") as f:
        f.write(img_data)

Example: Native imageSize Parameter

import openai

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cute cat playing with yarn",
    size="16:9",
    imageSize="4K",  # Native Gemini parameter
    response_format="b64_json"
)

Alternative: Chat API Format

You can also generate images via the Chat Completions endpoint:

import openai

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

# Using chat endpoint for image generation
response = client.chat.completions.create(
    model="gemini-3-pro-image",
    size="1920x1080",
    quality="hd",
    messages=[{
        "role": "user",
        "content": "一座未来主义风格的城市"
    }]
)

print(response.choices[0].message.content)

Alternative: Claude Messages API Format

curl -X POST http://127.0.0.1:8045/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-antigravity" \
  -d '{
    "model": "gemini-3-pro-image",
    "size": "1280x720",
    "quality": "hd",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "一只可爱的猫咪"}
    ]
  }'

Model Suffix Format

You can specify aspect ratio and quality directly in the model name:

response = client.images.generate(
    model="gemini-3-pro-image-16-9-4k",  # 16:9 ratio + 4K quality
    prompt="Futuristic cityscape"
)

Suffix patterns:

Aspect ratio: -16-9, -9-16, -4-3, -3-4, -21-9, -1-1
Quality: -4k, -2k (no suffix = standard)

Examples:

gemini-3-pro-image-16-9-4k → 16:9 + 4K
gemini-3-pro-image-1-1-2k → Square + 2K
gemini-3-pro-image-21-9 → Ultrawide + Standard

Supported Sizes

Exact Dimensions

Size	Aspect Ratio	Use Case
`1024x1024`	1:1	Square, social media
`1920x1080`	16:9	Widescreen, desktop
`1080x1920`	9:16	Mobile, stories
`1280x720`	16:9	HD video thumbnail
`2560x1440`	16:9	2K desktop wallpaper
`3840x2160`	16:9	4K wallpaper

Aspect Ratios

Ratio	Description	Common Use
`1:1`	Square	Instagram posts
`16:9`	Widescreen	YouTube thumbnails
`9:16`	Portrait	TikTok, Reels
`4:3`	Classic	Presentations
`3:4`	Portrait	Pinterest
`21:9`	Ultrawide	Cinema, banners

Quality Levels

Quality	Native Size	Max Dimension	Token Cost
`standard`	1K	1024px	Low
`medium`	2K	2048px	Medium
`hd`	4K	4096px	High

Parameter Priority

When multiple size/quality parameters are provided:

Highest priority: imageSize parameter (4K, 2K, 1K)
Medium priority: quality parameter (hd, medium, standard)
Lowest priority: Model suffix (-4k, -2k)

Example:

# imageSize takes precedence
response = client.images.generate(
    model="gemini-3-pro-image-2k",  # Suffix: 2K
    quality="hd",                    # Quality: 4K
    imageSize="1K",                  # WINS: 1K
    prompt="Mountain landscape"
)
# Actual resolution: 1K (from imageSize)

Prompt Engineering Tips

Be Specific

❌ Bad: “A city” ✅ Good: “A futuristic cyberpunk city at night with neon signs, rain-slicked streets, and flying vehicles”

Include Style

Art style: “digital art”, “oil painting”, “watercolor”, “3D render”
Artist reference: “in the style of Studio Ghibli”, “Greg Rutkowski style”
Mood: “moody”, “vibrant”, “minimalist”, “dramatic lighting”

Structure

Good prompt structure:

Subject: What to generate
Style: Artistic style/medium
Details: Colors, composition, lighting
Quality: “highly detailed”, “8k”, “photorealistic”

Example:

"A majestic dragon perched on a mountain peak, 
digital art, vibrant sunset colors with purple and orange sky, 
dramatic backlighting, highly detailed scales, 8k quality"

Error Handling

import openai

try:
    response = client.images.generate(
        model="gemini-3-pro-image",
        prompt="Test image",
        size="1920x1080"
    )
except openai.APIError as e:
    print(f"API Error: {e}")
except openai.AuthenticationError as e:
    print(f"Authentication failed: {e}")

Quota Management

Image generation consumes quota from the configured account. Antigravity Manager:

Automatically refreshes quota after successful generation
Rotates accounts when quota is exhausted
Displays real-time quota in the dashboard

Features

Flexible Sizing: Supports both exact dimensions and aspect ratios
Quality Control: Three quality levels (1K/2K/4K)
Multi-format: Base64 JSON or Data URI output
Batch Generation: Generate up to 10 images per request
Auto Quota Refresh: Real-time quota updates
Multiple Protocols: Works with OpenAI, Claude, and Chat APIs
Smart Defaults: Sensible defaults for quick testing

Limitations

Maximum 10 images per request (n parameter)
Custom sizes auto-mapped to supported aspect ratios
Person generation controlled by safety settings
Quota varies by account tier (Pro/Ultra/Free)

Overview

Endpoints

Protocol Conversion

Image Generation - /v1/images/generations

Endpoint

Authentication

Request Headers

Request Body

Response Format

Example: Basic Generation

Example: Python SDK

Example: Multiple Sizes

Example: Native imageSize Parameter

Alternative: Chat API Format

Alternative: Claude Messages API Format

Model Suffix Format

Supported Sizes

Exact Dimensions

Aspect Ratios

Quality Levels

Parameter Priority

Prompt Engineering Tips

Be Specific

Include Style

Structure

Error Handling

Quota Management

Features

Limitations

​Endpoint

​Authentication

​Request Headers

​Request Body

​Response Format

​Example: Basic Generation

​Example: Python SDK

​Example: Multiple Sizes

​Example: Native imageSize Parameter

​Alternative: Chat API Format

​Alternative: Claude Messages API Format

​Model Suffix Format

​Supported Sizes

​Exact Dimensions

​Aspect Ratios

​Quality Levels

​Parameter Priority

​Prompt Engineering Tips

​Be Specific

​Include Style

​Structure

​Error Handling

​Quota Management

​Features

​Limitations

Endpoint

Authentication

Request Headers

Request Body

Response Format

Example: Basic Generation

Example: Python SDK

Example: Multiple Sizes

Example: Native imageSize Parameter

Alternative: Chat API Format

Alternative: Claude Messages API Format

Model Suffix Format

Supported Sizes

Exact Dimensions

Aspect Ratios

Quality Levels

Parameter Priority

Prompt Engineering Tips

Be Specific

Include Style

Structure

Error Handling

Quota Management

Features

Limitations