Image Generation API

Beta Access: The Image API is currently in beta and available only to whitelisted users. Please contact support to request access.

The Demeterics Image API provides a unified image generation interface across multiple providers. Create images from text prompts with a single API while automatically tracking usage, costs, and storing generated images for analysis.

Overview

Base URL: https://api.demeterics.com/imagen/v1

Features:

• Unified API: Single endpoint for OpenAI, Google (Gemini/Imagen), Stability AI, and Leonardo AI
• Auto-tracking: Every request logged to BigQuery with full observability
• Image Storage: Generated images stored in GCS with 15-minute signed URLs
• BYOK Support: Use your own provider API keys with dual-key authentication
• Cost Control: Automatic credit billing with 15% managed or 10% BYOK fee

Authentication

Managed Keys (Default)

Use only your Demeterics API key:

curl -X POST https://api.demeterics.com/imagen/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{...}'

Bring Your Own Key (BYOK)

Use the dual-key format to provide your own provider API key:

curl -X POST https://api.demeterics.com/imagen/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key;sk-your_openai_key" \
  -H "Content-Type: application/json" \
  -d '{...}'

The format is: [demeterics_api_key];[provider_api_key]

BYOK Benefits:

• 10% service fee instead of 15%
• Use your own rate limits and quotas
• Provider costs billed directly to your account

Endpoints

Generate Images

POST /imagen/v1/generate

Generate images from a text prompt.

Request Body:

Example Request:

curl -X POST https://api.demeterics.com/imagen/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-image-1",
    "prompt": "A serene mountain landscape at sunset with a lake reflection",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

Response:

{
  "id": "01JARV4HZ6XPQMWVCS9N1GKEFD",
  "provider": "openai",
  "model": "gpt-image-1",
  "images": [
    {
      "url": "https://storage.googleapis.com/demeterics-data/imagen/...",
      "width": 1024,
      "height": 1024,
      "size_bytes": 1245678
    }
  ],
  "cost_usd": 0.04,
  "usage": {
    "image_count": 1,
    "resolution": "1024x1024",
    "quality": "hd",
    "prompt_tokens": 15
  },
  "metadata": {
    "generation_ms": 12500,
    "seed": 42,
    "revised_prompt": "A serene mountain landscape..."
  }
}

Providers

OpenAI Image Generation

Models:

• gpt-image-1 - Premium model with best quality and prompt following
• gpt-image-1-mini - Cost-effective model, ~70% cheaper

Supported Sizes:

• 1024x1024 (square)
• 1536x1024 (landscape)
• 1024x1536 (portrait)
• auto (let AI choose)

Quality Options:

• low - Fastest, lowest cost
• medium - Balanced quality and cost (default)
• high - Highest detail, most expensive

Max Images: 4 per request

Google Imagen

Models:

• gemini-2.5-flash-image - Recommended - Native Gemini image generation, fast and high quality
• imagen-4.0-generate-001 - Latest Imagen 4.0
• imagen-3.0-generate-002 - Imagen 3.0
• imagen-3.0-fast-generate-001 - Fast generation

Supported Sizes:

• 1024x1024
• 1536x1536
• 1280x768
• 768x1280

Features:

• Negative prompts supported
• Seed control for reproducibility

Max Images: 4 per request (1 for Gemini)

Leonardo AI

Models:

• phoenix - Flagship model, best overall quality
• kino-xl - Cinematic and dramatic style
• vision-xl - High-fidelity photorealistic images
• diffusion-xl - General purpose, versatile output
• lightning-xl - Fast generation, lower cost
• anime-xl - Optimized for anime style

Supported Sizes:

• 1024x1024 (1:1 Square)
• 1472x832 (16:9 Landscape)
• 832x1472 (9:16 Portrait)
• 1280x832 (3:2 Landscape)
• 832x1280 (2:3 Portrait)
• 1152x896 (4:3 Landscape)
• 896x1152 (3:4 Portrait)
• 512x512 (1:1 Small)

Quality Options (Alchemy):

• fast - No Alchemy, fastest generation
• standard - Alchemy v1, balanced quality (default)
• high - Alchemy v2, best quality enhancement

Features:

• Negative prompts supported
• Seed control for reproducibility
• Async generation with polling

Max Images: 4 per request

Stability AI

Models:

• ultra - Stable Image Ultra (highest quality, $0.08/image)
• core - Stable Image Core (balanced, $0.03/image)
• sd3-large - SD3 Large ($0.065/image)
• sd3-medium - SD3 Medium ($0.035/image)

Supported Sizes (based on official aspect ratios):

• 1024x1024 (1:1 Square)
• 1344x768 (16:9 Landscape)
• 768x1344 (9:16 Portrait)
• 1216x832 (3:2 Landscape)
• 832x1216 (2:3 Portrait)
• 1088x896 (5:4 Landscape)
• 896x1088 (4:5 Portrait)
• 1536x640 (21:9 Ultra-wide)
• 640x1536 (9:21 Ultra-tall)

Features:

• Negative prompts fully supported
• Seed control for reproducibility
• All models use aspect_ratio parameter

Max Images: 4 per request

Pricing

Managed Keys

Per-image pricing with 15% service fee:

BYOK

10% service fee on top of provider costs. Provider costs billed directly to your account.

Error Handling

Error Response Format:

{
  "error": {
    "type": "invalid_request",
    "message": "Prompt contains prohibited content",
    "code": "content_policy_violation"
  }
}

Common Error Codes:

Data Tracking

Every image generation is automatically tracked in BigQuery with:

• Transaction ID (ULID)
• User and API key identifiers
• Provider and model used
• Prompt hash (privacy-safe)
• Prompt token count
• Negative prompt flag
• Size, quality, and style settings
• Image count and seeds
• Revised prompt (if provider modified it)
• GCS storage paths for all images
• Cost breakdown (provider cost, service fee, total)
• Latency metrics
• Error information (if failed)

Query your image generations:

SELECT
  transaction_id,
  provider,
  model,
  imagen.size,
  imagen.quality,
  imagen.image_count,
  total_cost,
  imagen.gcs_paths
FROM `demeterics.demeterics.interactions`
WHERE interaction_type = 'imagen'
  AND user_id = @user_id
  AND timing.question_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
ORDER BY timing.question_time DESC

SDK Support

Python

import requests

response = requests.post(
    "https://api.demeterics.com/imagen/v1/generate",
    headers={"Authorization": "Bearer dmt_your_api_key"},
    json={
        "provider": "openai",
        "prompt": "A futuristic cityscape at night",
        "size": "1024x1024",
        "quality": "hd"
    }
)

images = response.json()["images"]
for img in images:
    print(f"Image URL: {img['url']}")

Node.js

const response = await fetch("https://api.demeterics.com/imagen/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dmt_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    provider: "openai",
    prompt: "A futuristic cityscape at night",
    size: "1024x1024",
    quality: "hd"
  })
});

const { images } = await response.json();
images.forEach(img => console.log(`Image URL: ${img.url}`));

Best Practices

1. Choose the right provider: OpenAI for quality, Stability for control, Google for speed
2. Use negative prompts: Specify what to avoid for better results (Stability, Google)
3. Set seeds for reproducibility: Use the same seed to get consistent results
4. Optimize image sizes: Use smaller sizes for drafts, HD for final outputs
5. Cache images: Download and store generated images if needed long-term (URLs expire in 15 minutes)
6. Monitor costs: Track usage in your Demeterics dashboard
7. Handle content policies: Different providers have different content restrictions
8. Batch wisely: Generate multiple variations with n parameter when exploring ideas