Ideogram Cost Tuning

Overview

Minimize Ideogram API spending by selecting the right model per task, caching identical prompts, batching images per call, and tracking credit burn rate. Ideogram bills per image generated at a flat rate that varies by model and rendering speed.

Pricing Reference

Prices approximate; check ideogram.ai/features/api-pricing for current rates.

Instructions

Step 1: Two-Phase Generation Workflow

// Draft with TURBO (cheap), finalize with V_2 (quality)
async function costEfficientGeneration(prompt: string, iterations = 5) {
  // Phase 1: Generate drafts cheaply
  const drafts = [];
  for (let i = 0; i < iterations; i++) {
    const result = await generateImage(prompt, { model: "V_2_TURBO" });
    drafts.push(result);
  }
  // Cost: 5 x $0.05 = $0.25

  // Phase 2: Pick best seed, regenerate at full quality
  const bestSeed = await selectBestDraft(drafts); // manual or automated
  const final = await generateImage(prompt, { model: "V_2", seed: bestSeed });
  // Cost: 1 x $0.08 = $0.08

  // Total: $0.33 instead of $0.40 (5 x V_2)
  return final;
}

Step 2: Batch Images Per Call

// Single API call for up to 4 images costs the same as 4 separate calls
// BUT saves latency (one round-trip instead of four)
async function generateVariations(prompt: string) {
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt,
        model: "V_2_TURBO",
        num_images: 4, // 4 images in one call
        magic_prompt_option: "AUTO",
      },
    }),
  });

  const result = await response.json();
  return result.data; // 4 image objects
}

Step 3: Cache Identical Prompts

import { createHash } from "crypto";

const cache = new Map<string, { url: string; seed: number; cachedAt: number }>(

Ideogram Data Handling

Overview

Manage generated image assets from Ideogram's API. Critical concern: Ideogram image URLs expire (approximately 1 hour). Every generation must be downloaded and persisted immediately. This skill covers metadata tracking, download pipelines, local and cloud storage, lifecycle management, and generation history for reproducibility.

Prerequisites

• IDEOGRAM_API_KEY configured
• Storage solution (local filesystem, S3, or GCS)
• Database for generation metadata (SQLite, Postgres, or JSON files)

Instructions

Step 1: Generation Record Schema

interface GenerationRecord {
  id: string;                // Unique identifier
  prompt: string;            // Original prompt
  expandedPrompt?: string;   // Magic Prompt expansion (from response)
  negativePrompt?: string;   // Negative prompt used
  model: string;             // V_2, V_2_TURBO, etc.
  styleType: string;         // DESIGN, REALISTIC, etc.
  aspectRatio: string;       // ASPECT_16_9, etc.
  seed: number;              // For reproducibility
  resolution: string;        // e.g., "1024x1024"
  isSafe: boolean;           // is_image_safe from response
  originalUrl: string;       // Temporary Ideogram URL
  storedPath: string;        // Local or S3 path
  createdAt: string;         // ISO timestamp
  sizeBytes?: number;        // Downloaded file size
  tags?: string[];           // User-defined tags
}

Step 2: Generate, Download, and Track

import { writeFileSync, mkdirSync, statSync } from "fs";
import { join } from "path";
import { randomUUID } from "crypto";

const STORAGE_DIR = "./generated-images";
const records: GenerationRecord[] = [];

async function generateAndPersist(
  prompt: string,
  options: {
    model?: string;
    style_type?: string;
    aspect_ratio?: string;
    negative_prompt?: string;
    seed?: number;
    tags?: string[];
  } = {}
): Promise<GenerationRecord> {
  // Generate
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt,
        model: options.model ?? "V_2",
        style_type: options.style_type ?? "AUTO",
        aspect_ratio: options.aspect_ratio ?? "ASPECT_1_1",
        magic_prompt_option: "AUTO",
        negative_prompt: options.negative_prompt,
        seed: options.seed,
      },
    }),
  });

  if (!response.ok) throw new Error(`Generation failed: ${response.status}`);
  const result = await response.json();
  const image = result.data[0];

  // Download IMMEDIATELY (URLs

Ideogram Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A' !echo "IDEOGRAM_API_KEY set: ${IDEOGRAM_API_KEY:+YES}${IDEOGRAM_API_KEY:-NO}"

Overview

Collect diagnostic information for Ideogram API issues. Produces a tarball with environment details, API connectivity tests, request/response samples, and redacted configuration -- suitable for attaching to support tickets.

Prerequisites

• IDEOGRAM_API_KEY environment variable set
• curl and tar available
• Permission to collect environment info

Instructions

Step 1: Full Debug Bundle Script

#!/bin/bash
set -euo pipefail

BUNDLE_DIR="ideogram-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

cat > "$BUNDLE_DIR/summary.txt" <<HEADER
=== Ideogram Debug Bundle ===
Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
Hostname: $(hostname)
HEADER

# --- Environment ---
{
  echo "--- Runtime ---"
  echo "Node: $(node --version 2>/dev/null || echo 'not installed')"
  echo "Python: $(python3 --version 2>/dev/null || echo 'not installed')"
  echo "OS: $(uname -srm)"
  echo ""
  echo "--- Ideogram Config ---"
  echo "API Key: ${IDEOGRAM_API_KEY:+SET (length=${#IDEOGRAM_API_KEY})}${IDEOGRAM_API_KEY:-NOT SET}"
} >> "$BUNDLE_DIR/summary.txt"

# --- API Connectivity Test ---
{
  echo ""
  echo "--- API Test (Legacy Generate) ---"
  RESPONSE=$(curl -s -w "\nHTTP_STATUS:%{http_code}\nTIME_TOTAL:%{time_total}" \
    -X POST https://api.ideogram.ai/generate \
    -H "Api-Key: ${IDEOGRAM_API_KEY:-missing}" \
    -H "Content-Type: application/json" \
    -d '{"image_request":{"prompt":"debug test","model":"V_2_TURBO","magic_prompt_option":"OFF"}}' \
    2>&1 || echo "CURL_FAILED")
  echo "$RESPONSE" | grep -E "HTTP_STATUS|TIME_TOTAL|error" || true
  echo "$RESPONSE" | head -5 > "$BUNDLE_DIR/api-response-sample.json"
} >> "$BUNDLE_DIR/summary.txt"

# --- DNS Resolution ---
{
  echo ""
  echo "--- DNS & Network ---"
  echo "DNS resolve: $(nslookup api.ideogram.ai 2>/dev/null | grep -A1 'Name:' | tail -1 || echo 'nslookup unavailable')"
  echo "TLS test: $(curl -s -o /dev/null -w '%{ssl_verify_result}' https://api.ideogram.ai/ 2>/dev/null || echo 'failed')"
} >> "$BUNDLE_DIR/summary.txt"

# --- Local Configuration (redacted) ---
if [ -f .env ]; then
  sed 's/=.*/=***REDACTED***/' .env >

Ideogram Deploy Integration

Overview

Deploy Ideogram image generation endpoints to Vercel, Cloud Run, or Docker. Key concerns: API key security, function timeouts (generation takes 5-15s), image persistence (URLs expire), and CDN integration for serving generated images.

Prerequisites

• IDEOGRAM_API_KEY configured
• Cloud storage for generated images (S3, GCS, or R2)
• Platform CLI installed (vercel, gcloud, or docker)

Instructions

Step 1: API Endpoint (Next.js / Vercel)

// app/api/generate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: process.env.AWS_REGION });

export async function POST(req: NextRequest) {
  const { prompt, style, aspectRatio } = await req.json();

  if (!prompt || prompt.length > 10000) {
    return NextResponse.json({ error: "Invalid prompt" }, { status: 400 });
  }

  // Generate image via Ideogram
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt,
        model: "V_2",
        style_type: style || "AUTO",
        aspect_ratio: aspectRatio || "ASPECT_1_1",
        magic_prompt_option: "AUTO",
      },
    }),
  });

  if (!response.ok) {
    const err = await response.text();
    return NextResponse.json({ error: `Generation failed: ${response.status}` }, { status: 502 });
  }

  const result = await response.json();
  const image = result.data[0];

  // Download and persist to S3 (Ideogram URLs expire)
  const imgResponse = await fetch(image.url);
  const buffer = Buffer.from(await imgResponse.arrayBuffer());
  const key = `generated/${image.seed}-${Date.now()}.png`;

  await s3.send(new PutObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
    Body: buffer,
    ContentType: "image/png",
  }));

  return NextResponse.json({
    url: `https://${process.env.CDN_DOMAIN}/${key}`,
    seed: image.seed,
    resolution: image.resolution,
    style: image.style_type,
  });
}

export const maxDuration = 60; // Vercel function timeout

Step 2: Vercel Configuration

{
  "functions": {
    "app/api/generate/route.ts": {
      "maxDuration": 60
    }
  },
  "env": {
    "IDEOGRAM_API_KEY": "@ideogram-api-key"
  }
}

set -euo pipefail
# Set secrets
vercel env add IDEOGRAM_API_KEY production
vercel env add S3_BUCKET production
vercel env add CDN_DOMAIN production

Ste

Ideogram Hello World

Overview

Generate your first AI image with Ideogram. Demonstrates the legacy /generate endpoint (JSON body) and the V3 /v1/ideogram-v3/generate endpoint (multipart form). Both return temporary image URLs that must be downloaded promptly.

Prerequisites

• Completed ideogram-install-auth setup
• IDEOGRAM_API_KEY environment variable set
• Node.js 18+ or Python 3.10+

Instructions

Step 1: Quick Test with curl

set -euo pipefail
# Legacy endpoint (V_2 model, JSON body)
curl -s -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_request": {
      "prompt": "A cheerful golden retriever wearing sunglasses on a beach, with text saying \"Hello Ideogram!\"",
      "model": "V_2",
      "style_type": "REALISTIC",
      "aspect_ratio": "ASPECT_16_9",
      "magic_prompt_option": "AUTO"
    }
  }' | jq '.data[0] | {url, seed, resolution, is_image_safe}'

Step 2: TypeScript -- Generate and Download

// hello-ideogram.ts
import { writeFileSync } from "fs";

async function helloIdeogram() {
  // Generate an image with embedded text (Ideogram's specialty)
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt: 'Modern poster design with bold text "HELLO WORLD" in neon gradient, dark background, clean typography',
        model: "V_2",
        style_type: "DESIGN",
        aspect_ratio: "ASPECT_1_1",
        magic_prompt_option: "AUTO",
        num_images: 1,
      },
    }),
  });

  if (!response.ok) {
    throw new Error(`Generation failed: ${response.status} ${await response.text()}`);
  }

  const result = await response.json();
  const image = result.data[0];

  console.log("Generated image:");
  console.log("  URL:", image.url);
  console.log("  Seed:", image.seed);
  console.log("  Resolution:", image.resolution);
  console.log("  Style:", image.style_type);
  console.log("  Safe:", image.is_image_safe);

  // Download immediately -- URLs expire after ~1 hour
  const imgResponse = await fetch(image.url);
  const buffer = Buffer.from(await imgResponse.arrayBuffer());
  writeFileSync("hello-ideogram.png", buffer);
  console.log("Saved to hello-ideogram.png");
}

helloIdeogram().cat

Ideogram Incident Runbook

Overview

Rapid incident response for Ideogram API outages, auth failures, rate limiting, and degraded generation quality. Covers triage, immediate remediation, fallback activation, and postmortem process.

Severity Levels

Quick Triage (Run These First)

set -euo pipefail

echo "=== IDEOGRAM TRIAGE ==="

# 1. Test API connectivity and auth
echo -n "API status: "
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request":{"prompt":"triage test","model":"V_2_TURBO","magic_prompt_option":"OFF"}}'
echo ""

# 2. Test V3 endpoint
echo -n "V3 status: "
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.ideogram.ai/v1/ideogram-v3/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -F "prompt=triage test" -F "rendering_speed=FLASH"
echo ""

# 3. Check DNS resolution
echo -n "DNS: "
nslookup api.ideogram.ai 2>/dev/null | grep -A1 "Name:" | tail -1 || echo "lookup failed"

# 4. Measure latency
echo -n "Latency: "
curl -s -o /dev/null -w "%{time_total}s" \
  -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request":{"prompt":"latency test","model":"V_2_TURBO","magic_prompt_option":"OFF"}}'
echo ""

Decision Tree

Is api.ideogram.ai returning errors?
├─ YES: What status code?
│   ├─ 401 → Key revoked or misconfigured. See "Auth Failure" below.
│   ├─ 402 → Credits exhausted. Top up immediately.
│   ├─ 422 → Safety filter. Prompt issue, not outage.
│   ├─ 429 → Rate limited. Reduce concurrency.
│   ├─ 500/503 → Ideogram outage. Enable fallback.
│   └─ Timeout → Network or Ideogram performance issue.
├─ NO: Are images generating but quality is bad?
│   ├─ YES → Check model version, style params, magic_prompt setting.

Ideogram Install & Auth

Overview

Set up Ideogram API authentication for AI image generation. Ideogram provides a REST API at api.ideogram.ai for text-to-image generation, editing, remixing, upscaling, and describing images. Authentication uses an Api-Key header on every request.

Prerequisites

• Node.js 18+ or Python 3.10+
• Ideogram account at ideogram.ai
• API key from Ideogram dashboard (Settings > API Beta)
• Payment method configured (auto top-up billing)

Instructions

Step 1: Get Your API Key

1. Log into ideogram.ai
2. Navigate to Settings (burger icon) > API Beta
3. Accept the Developer API Agreement
4. Click Manage Payment and add billing info via Stripe
5. Click Create API key -- store it immediately, it is shown only once

Step 2: Install HTTP Client

set -euo pipefail
# Node.js (no SDK required -- Ideogram uses a plain REST API)
npm install dotenv

# Python
pip install requests python-dotenv

Step 3: Configure Authentication

# Create .env file (NEVER commit to git)
echo 'IDEOGRAM_API_KEY=your-api-key-here' >> .env

# Add to .gitignore
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore

Step 4: Verify Connection

// verify-ideogram.ts
import "dotenv/config";

async function verifyIdeogramAuth() {
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt: "A simple blue circle on white background",
        model: "V_2_TURBO",
        aspect_ratio: "ASPECT_1_1",
        magic_prompt_option: "OFF",
      },
    }),
  });

  if (response.ok) {
    const result = await response.json();
    console.log("Auth verified. Image URL:", result.data[0].url);
    console.log("Seed:", result.data[0].seed);
  } else {
    const err = await response.text();
    console.error(`Auth failed (${response.status}):`, err);
  }
}

verifyIdeogramAuth();

# verify_ideogram.py
import os, requests
from dotenv import load_dotenv

load_dotenv()

response = requests.post(
    "https://api.ideogram.ai/generate",
    headers={
        "Api-Key": os.environ["IDEOGRAM_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "image_request"

Ideogram Local Dev Loop

Overview

Set up a fast local development workflow for Ideogram integrations. Includes a typed client wrapper, mock server for offline development (avoids burning credits), and vitest integration for automated testing.

Prerequisites

• Completed ideogram-install-auth setup
• Node.js 18+ with npm/pnpm
• IDEOGRAM_API_KEY environment variable set

Instructions

Step 1: Create Project Structure

my-ideogram-project/
├── src/
│   ├── ideogram/
│   │   ├── client.ts       # Typed Ideogram client wrapper
│   │   ├── types.ts         # Request/response type definitions
│   │   └── mock-server.ts   # Local mock for offline dev
│   └── index.ts
├── tests/
│   └── ideogram.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
├── tsconfig.json
└── package.json

Step 2: Install Dependencies

set -euo pipefail
npm install dotenv
npm install -D typescript tsx vitest @types/node

Step 3: Type Definitions

// src/ideogram/types.ts
export type StyleType = "AUTO" | "GENERAL" | "REALISTIC" | "DESIGN" | "RENDER_3D" | "ANIME";
export type AspectRatio = "ASPECT_1_1" | "ASPECT_16_9" | "ASPECT_9_16" | "ASPECT_3_2" | "ASPECT_2_3"
  | "ASPECT_4_3" | "ASPECT_3_4" | "ASPECT_10_16" | "ASPECT_16_10" | "ASPECT_1_3" | "ASPECT_3_1";
export type Model = "V_1" | "V_1_TURBO" | "V_2" | "V_2_TURBO" | "V_2A" | "V_2A_TURBO";
export type MagicPrompt = "AUTO" | "ON" | "OFF";

export interface GenerateRequest {
  prompt: string;
  model?: Model;
  style_type?: StyleType;
  aspect_ratio?: AspectRatio;
  magic_prompt_option?: MagicPrompt;
  negative_prompt?: string;
  num_images?: number;
  seed?: number;
}

export interface ImageResult {
  url: string;
  prompt: string;
  resolution: string;
  is_image_safe: boolean;
  seed: number;
  style_type: StyleType;
}

export interface GenerateResponse {
  created: string;
  data: ImageResult[];
}

Step 4: Client Wrapper

// src/ideogram/client.ts
import type { GenerateRequest, GenerateResponse } from "./types";

const IDEOGRAM_API = "https://api.ideogram.ai";

export class IdeogramClient {
  constructor(private apiKey: string) {
    if (!apiKey) throw new Error("IDEOGRAM_API_KEY is required");
  }

  async generate(request: GenerateRequest): Promise<GenerateResponse> {
    const response = await fetch(`${IDEOGRAM_API}/generate`, {
      method: "POST",
      headers: {
        "Api-Key&

Ideogram Migration Deep Dive

Current State

!npm list 2>/dev/null | head -10

Overview

Comprehensive migration guide for moving to Ideogram from DALL-E, Midjourney, Stable Diffusion, or another image generation provider. Uses the strangler fig pattern for gradual migration. Key Ideogram advantages: superior text rendering in images, REST API with no SDK dependency, and flexible style/aspect ratio control.

Migration Types

Instructions

Step 1: Audit Current Integration

set -euo pipefail
# Find all image generation API calls
grep -rn "openai\|dall-e\|dalle\|midjourney\|stability\|stablediffusion" \
  --include="*.ts" --include="*.js" --include="*.py" . | head -30

# Count integration points
echo "Integration points:"
grep -rl "images/generations\|api.openai.com\|api.stability.ai" \
  --include="*.ts" --include="*.js" . | wc -l

Step 2: API Mapping -- DALL-E to Ideogram

// === DALL-E (Before) ===
const dallEResponse = await fetch("https://api.openai.com/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "dall-e-3",
    prompt: "A sunset over mountains",
    n: 1,
    size: "1024x1024",
    quality: "standard",
    style: "natural",
  }),
});
const dallEResult = await dallEResponse.json();
const imageUrl = dallEResult.data[0].url;

// === Ideogram (After) ===
const ideogramResponse = await fetch("https://api.ideogram.ai/generate", {
  method: "POST",
  headers: {
    "Api-Key": process.env.IDEOGRAM_API_KEY!,  // Note: Api-Key, not Authorization
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image_request: {                             // Note: wrapped in image_request
      prompt: "A sunset over mountains",
      model: "V_2",
      aspect_ratio: "ASPECT_1_1",               // Note: enum, not "1024x1024"
      style_type: "REALISTIC",                   // Note: different 

Ideogram Multi-Environment Setup

Overview

Configure Ideogram API access across development, staging, and production with isolated API keys, environment-specific model/speed settings, and proper secret management. Each environment gets its own key and configuration to prevent cross-environment issues.

Environment Strategy

Instructions

Step 1: Configuration Structure

// config/ideogram.ts
type Environment = "development" | "staging" | "production";

interface IdeogramConfig {
  apiKey: string;
  defaultModel: string;
  renderingSpeed: string;
  timeout: number;
  maxRetries: number;
  concurrency: number;
  cache: { enabled: boolean; ttlSeconds: number };
  debug: boolean;
}

const configs: Record<Environment, Omit<IdeogramConfig, "apiKey">> = {
  development: {
    defaultModel: "V_2_TURBO",
    renderingSpeed: "TURBO",
    timeout: 30000,
    maxRetries: 1,
    concurrency: 2,
    cache: { enabled: false, ttlSeconds: 60 },
    debug: true,
  },
  staging: {
    defaultModel: "V_2",
    renderingSpeed: "DEFAULT",
    timeout: 60000,
    maxRetries: 3,
    concurrency: 5,
    cache: { enabled: true, ttlSeconds: 300 },
    debug: false,
  },
  production: {
    defaultModel: "V_2",
    renderingSpeed: "DEFAULT",
    timeout: 60000,
    maxRetries: 5,
    concurrency: 8,
    cache: { enabled: true, ttlSeconds: 600 },
    debug: false,
  },
};

export function getIdeogramConfig(): IdeogramConfig {
  const env = detectEnvironment();
  const apiKey = getApiKeyForEnv(env);

  if (!apiKey) {
    throw new Error(`IDEOGRAM_API_KEY not set for environment: ${env}`);
  }

  return { ...configs[env], apiKey };
}

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || "development";
  if (env === "production") return "production";
  if (env === "staging" || process.env.VERCEL_ENV === "preview") return "staging";
  return "development";
}

function getApiKeyForEnv(env: Environment): string {
  const envVar = {
    development: "IDEOGRAM_API_KEY_DEV",
    staging: "IDEOGRAM_API_KEY_STAGING",
    production: "IDEOGRAM_API_KEY",
  }[env];

  return process.env[envVar] || process.env.IDEOGRAM_API_

Ideogram Observability

Overview

Monitor Ideogram AI image generation for latency, cost, error rates, and content safety rejections. Key metrics: generation duration (5-25s depending on model), credit burn rate, safety filter rejection rate, and API availability. Ideogram's API is synchronous, so all observability is request-level instrumentation.

Key Metrics

Instructions

Step 1: Instrumented Generation Wrapper

import { performance } from "perf_hooks";

interface GenerationMetrics {
  duration: number;
  model: string;
  style: string;
  status: "success" | "error" | "safety_rejected" | "rate_limited";
  seed?: number;
  resolution?: string;
}

const metricsLog: GenerationMetrics[] = [];

async function instrumentedGenerate(
  prompt: string,
  options: { model?: string; style_type?: string; aspect_ratio?: string } = {}
) {
  const model = options.model ?? "V_2";
  const style = options.style_type ?? "AUTO";
  const start = performance.now();

  try {
    const response = await fetch("https://api.ideogram.ai/generate", {
      method: "POST",
      headers: {
        "Api-Key": process.env.IDEOGRAM_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        image_request: { prompt, model, style_type: style, ...options, magic_prompt_option: "AUTO" },
      }),
    });

    const duration = performance.now() - start;

    if (response.status === 422) {
      recordMetric({ duration, model, style, status: "safety_rejected" });
      throw new Error("Safety filter rejected prompt");
    }
    if (response.status === 429) {
      recordMetric({ duration, model, style, status: "rate_limited" });
      throw new Error("Rate limited");
    }
    if (!response.ok) {
      recordMetric({ duration, model, style, status: "error" });
      throw new Error(`API error: ${response.status}`);
    }

    const result = await response.json();
    const image = result.data[0];

    recordMetric({
      duration, model, s

Ideogram Performance Tuning

Overview

Optimize Ideogram image generation for speed, cost, and throughput. Key levers: model and rendering speed selection, prompt-based caching, parallel generation with concurrency limits, and CDN delivery of generated assets.

Performance Baselines

Instructions

Step 1: Speed Tiers by Use Case

const SPEED_CONFIGS = {
  // Preview / draft mode -- fastest, cheapest
  preview: {
    endpoint: "https://api.ideogram.ai/generate",
    model: "V_2_TURBO",
    note: "3-6s, good enough for iteration",
  },
  // Standard production -- balanced
  standard: {
    endpoint: "https://api.ideogram.ai/generate",
    model: "V_2",
    note: "8-15s, high quality for final assets",
  },
  // V3 with speed control
  v3_fast: {
    endpoint: "https://api.ideogram.ai/v1/ideogram-v3/generate",
    rendering_speed: "TURBO",
    note: "4-8s, V3 quality at faster speed",
  },
  v3_quality: {
    endpoint: "https://api.ideogram.ai/v1/ideogram-v3/generate",
    rendering_speed: "QUALITY",
    note: "15-25s, maximum quality",
  },
} as const;

function getConfig(tier: keyof typeof SPEED_CONFIGS) {
  return SPEED_CONFIGS[tier];
}

Step 2: Prompt-Based Cache Layer

import { createHash } from "crypto";
import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
import { join } from "path";

const CACHE_DIR = "./ideogram-cache";

function cacheKey(prompt: string, style: string, aspect: string): string {
  return createHash("sha256")
    .update(`${prompt.toLowerCase().trim()}:${style}:${aspect}`)
    .digest("hex")
    .slice(0, 16);
}

async function cachedGenerate(
  prompt: string,
  options: { style_type?: string; aspect_ratio?: string; model?: string } = {}
) {
  const style = options.style_type ?? "AUTO";
  const aspect = options.aspect_ratio ?? "ASPECT_1_1";
  const key = cacheKey(prompt, style, aspect);
  const metaPath = join(CACHE_DIR, `${key}.json`);
  const imgPath = join(CACHE_DIR, `${key}.png`);

  // Return cached if exists
  if (existsSync(metaPath) && existsSync(imgPath)) {
    conso

Ideogram Production Checklist

Overview

Complete pre-flight checklist for deploying Ideogram image generation to production. Covers API key management, timeout configuration, image persistence, error handling, monitoring, and rollback procedures.

Prerequisites

• Staging environment tested
• Production API key created (separate from dev)
• Image storage configured (S3, GCS, or R2)
• Monitoring stack ready

Pre-Deployment Checklist

API Configuration

• [ ] Production API key stored in secret manager (not .env file)
• [ ] Key is separate from dev/staging keys
• [ ] Auto top-up billing configured with appropriate limits
• [ ] Base URL is https://api.ideogram.ai (no trailing slash)

Request Handling

• [ ] Api-Key header used (not Authorization: Bearer)
• [ ] Request timeout set to 60s+ (generation takes 5-15s, complex prompts longer)
• [ ] Retry logic with exponential backoff on 429 and 5xx
• [ ] Concurrency limited to 8 (below the 10 in-flight limit)
• [ ] Prompt length validated (max 10,000 chars)

Image Persistence

• [ ] Images downloaded immediately after generation (URLs expire ~1 hour)
• [ ] Downloaded to durable storage (S3/GCS/R2), not local filesystem
• [ ] Filenames include seed for reproducibility tracking
• [ ] Generation metadata (prompt, seed, model, style) stored in database

Error Handling

• [ ] 401 triggers key rotation alert
• [ ] 422 (safety filter) logged with sanitized prompt for review
• [ ] 429 handled with retry, not user-facing error
• [ ] 402 (no credits) triggers billing alert and graceful degradation
• [ ] Circuit breaker prevents cascading failures

Content Safety

• [ ] Prompt sanitization removes PII before API call
• [ ] User-submitted prompts validated server-side
• [ ] is_image_safe response field checked before displaying to users
• [ ] Content moderation layer for user-facing applications

Production Health Check

async function ideogramHealthCheck(): Promise<{
  status: "healthy" | "degraded" | "down";
  latencyMs: number;
  details: string;
}> {
  const start = Date.now();
  try {
    const response = await fetch("https://api.ideogram.ai/generate", {
      method: "POST",
      headers: {
        "Api-Key": process.env.IDEOGRAM_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        image_request: {
          prompt: "health check: simple blue dot",
          model: "V_2_TURBO",
          magic_prompt_option: "OFF",
        },
   

Ideogram Rate Limits

Overview

Handle Ideogram's rate limits with exponential backoff, request queuing, and concurrency control. Ideogram enforces a default limit of 10 in-flight requests (concurrent, not per-minute). Image generation takes 5-15 seconds per call, so this limit can be hit quickly during batch operations.

Prerequisites

• IDEOGRAM_API_KEY configured
• Understanding of async patterns
• p-queue npm package (optional, for queue-based approach)

Ideogram Rate Limit Model

Instructions

Step 1: Exponential Backoff with Jitter

async function withBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseMs: 1000, maxMs: 30000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err: any) {
      if (attempt === config.maxRetries) throw err;

      const status = err.status ?? err.response?.status;
      // Only retry on 429 (rate limited) or 5xx (server error)
      if (status && status !== 429 && status < 500) throw err;

      const exponential = config.baseMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponential + jitter, config.maxMs);

      console.warn(`Rate limited (attempt ${attempt + 1}/${config.maxRetries}). Waiting ${delay.toFixed(0)}ms`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

Step 2: Concurrency-Limited Queue

import PQueue from "p-queue";

// Ideogram allows 10 in-flight -- use 8 to leave headroom
const ideogramQueue = new PQueue({ concurrency: 8 });

async function queuedGenerate(prompt: string, options: any = {}) {
  return ideogramQueue.add(async () => {
    const response = await fetch("https://api.ideogram.ai/generate", {
      method: "POST",
      headers: {
        "Api-Key": process.env.IDEOGRAM_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        image_request: { prompt, model: "V_2", ...options },
      }),
    });

    if (response.status === 429) {
      t

Ideogram Reference Architecture

Overview

Production architecture for AI image generation with Ideogram at scale. Covers prompt templating for brand consistency, generation pipelines using all six API endpoints, asset storage and CDN delivery, and metadata tracking for reproducibility.

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│  Prompt Engineering Layer                                │
│  Templates │ Brand Guidelines │ Negative Prompts         │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Ideogram API (api.ideogram.ai)                          │
│  ┌──────────┐ ┌────────┐ ┌───────┐ ┌────────┐          │
│  │ Generate │ │ Edit   │ │ Remix │ │Describe│          │
│  │(text→img)│ │(inpaint)│ │(vary) │ │(img→txt)│         │
│  └────┬─────┘ └───┬────┘ └──┬────┘ └───┬────┘          │
│       │           │         │          │                │
│  ┌────┴───────────┴─────────┴──────────┘                │
│  │  ┌──────────┐  ┌─────────┐                           │
│  │  │ Upscale  │  │ Reframe │                           │
│  │  └────┬─────┘  └────┬────┘                           │
│  └───────┴──────────────┘                               │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Post-Processing & Storage                               │
│  Download │ Resize │ WebP Convert │ S3/GCS │ CDN        │
└─────────────────────────────────────────────────────────┘

Instructions

Step 1: Prompt Template System

interface PromptTemplate {
  name: string;
  base: string;
  style: string;
  negativePrompt: string;
  aspectRatio: string;
  model: string;
  renderingSpeed?: string;
}

const BRAND_TEMPLATES: Record<string, PromptTemplate> = {
  socialPost: {
    name: "Social Media Post",
    base: "{subject}, modern clean design, vibrant colors, professional",
    style: "DESIGN",
    negativePrompt: "blurry text, misspelled, watermark, low quality",
    aspectRatio: "ASPECT_1_1",
    model: "V_2",
  },
  blogHero: {
    name: "Blog Hero Image",
    base: "{subject}, editorial photography, wide composition, cinematic lighting",
    style: "REALISTIC",
    negativePrompt: "text overlay, watermark, blurry, oversaturated",
    aspectRatio: "ASPECT_16_9",
    model: "V_2",
  },
  storyVertical: {
    name: "Story / Reel",
    base: "{subject}, vertical composition, eye-catching, bold colors",
    style: "DESIGN",
    negativePrompt: "horizontal layout, small text, blurry",
    aspectRatio: 

Ideogram SDK Patterns

Overview

Production-ready patterns for Ideogram's REST API. Since Ideogram has no official SDK, these patterns provide type-safe wrappers, retry logic, response validation, and multi-tenant support for the api.ideogram.ai endpoints.

Prerequisites

• Completed ideogram-install-auth setup
• Familiarity with async/await and fetch API
• Understanding of Ideogram response lifecycle (URLs expire)

Instructions

Step 1: Singleton Client with Auto-Download

// src/ideogram/client.ts
import { writeFileSync, mkdirSync } from "fs";
import { join } from "path";

const API_BASE = "https://api.ideogram.ai";

let instance: IdeogramClient | null = null;

export function getIdeogramClient(): IdeogramClient {
  if (!instance) {
    const key = process.env.IDEOGRAM_API_KEY;
    if (!key) throw new Error("IDEOGRAM_API_KEY not set");
    instance = new IdeogramClient(key);
  }
  return instance;
}

export class IdeogramClient {
  constructor(private apiKey: string) {}

  async generate(prompt: string, options: {
    model?: string;
    style_type?: string;
    aspect_ratio?: string;
    negative_prompt?: string;
    magic_prompt_option?: string;
    num_images?: number;
    seed?: number;
  } = {}) {
    const response = await fetch(`${API_BASE}/generate`, {
      method: "POST",
      headers: { "Api-Key": this.apiKey, "Content-Type": "application/json" },
      body: JSON.stringify({
        image_request: {
          prompt,
          model: options.model ?? "V_2",
          style_type: options.style_type ?? "AUTO",
          aspect_ratio: options.aspect_ratio ?? "ASPECT_1_1",
          magic_prompt_option: options.magic_prompt_option ?? "AUTO",
          negative_prompt: options.negative_prompt,
          num_images: options.num_images ?? 1,
          seed: options.seed,
        },
      }),
    });
    return this.handleResponse(response);
  }

  async describe(imagePath: string) {
    const form = new FormData();
    const file = new Blob([await import("fs").then(fs => fs.readFileSync(imagePath))]);
    form.append("image_file", file, "image.png");
    const response = await fetch(`${API_BASE}/describe`, {
      method: "POST",
      headers: { "Api-Key": this.apiKey },
      body: form,
    });
    return this.handleResponse(response);
  }

  async downloadImage(url: string, outputDir: string, filename?: string): Promise<string> {
    mkdirSync(outputDir, { recursive: true });
    const imgResponse = await fetch(url);
    if (!imgResponse.ok) throw new Error(`Download failed: ${imgResponse.status}`);
    const buffer = Buffer.from(await imgResponse.arrayBuffer());
    const outPath = join(outputDir, filename ?? `ideogram

Ideogram Security Basics

Overview

Secure your Ideogram API integration. Ideogram uses a single Api-Key header for authentication -- there are no OAuth scopes, roles, or fine-grained permissions. Security focuses on key management, environment isolation, prompt sanitization, and preventing key exposure.

Prerequisites

• Ideogram API key from dashboard
• Understanding of environment variables
• .gitignore configured for secrets

Instructions

Step 1: Secure Key Storage

# .env (NEVER commit)
IDEOGRAM_API_KEY=your-key-here

# .gitignore -- add these lines
.env
.env.local
.env.*.local
*.key

// Validate key exists at startup -- fail fast
function requireApiKey(): string {
  const key = process.env.IDEOGRAM_API_KEY;
  if (!key || key.length < 10) {
    throw new Error("IDEOGRAM_API_KEY not set or invalid. Check .env file.");
  }
  return key;
}

Step 2: Key Rotation Procedure

Ideogram shows the full API key only once at creation. To rotate:

set -euo pipefail
# 1. Create new key in Ideogram dashboard (Settings > API Beta > Create API key)
# 2. Store new key immediately -- it won't be shown again

# 3. Update your environment
export IDEOGRAM_API_KEY="new-key-value"

# 4. Verify new key works
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request":{"prompt":"rotation test","model":"V_2_TURBO","magic_prompt_option":"OFF"}}'

# 5. Update deployment secrets
# Vercel: vercel env rm IDEOGRAM_API_KEY production && vercel env add IDEOGRAM_API_KEY production
# GitHub Actions: gh secret set IDEOGRAM_API_KEY
# AWS: aws secretsmanager update-secret --secret-id ideogram-api-key --secret-string "$IDEOGRAM_API_KEY"

# 6. Delete old key from Ideogram dashboard after confirming zero traffic

Step 3: Prevent Key Exposure

// Proxy pattern -- never expose API key to browser
// api/ideogram-proxy.ts (server-side only)
export async function POST(req: Request) {
  const { prompt, style } = await req.json();

  // Validate and sanitize before forwarding
  if (!prompt || prompt.length > 10000) {
    return Response.json({ error: "Invalid prompt" }, { status: 400 });
  }

  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!, // Server-side only
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
    

Ideogram Upgrade & Migration

Current State

!npm list 2>/dev/null | head -10

Overview

Guide for migrating between Ideogram API versions. The primary migration path is from the legacy /generate endpoint (JSON body, V_1/V_2 models) to the V3 endpoints (multipart form data, new parameters). This covers breaking changes in request format, model names, aspect ratio syntax, style types, and new capabilities.

Breaking Changes: Legacy to V3

Instructions

Step 1: Audit Current API Usage

set -euo pipefail
# Find all Ideogram API calls in your codebase
grep -rn "api.ideogram.ai" --include="*.ts" --include="*.js" --include="*.py" .
grep -rn "ASPECT_" --include="*.ts" --include="*.js" .
grep -rn "image_request" --include="*.ts" --include="*.js" .
grep -rn "magic_prompt_option" --include="*.ts" --include="*.js" .

Step 2: Create Adapter for Both Versions

// src/ideogram/adapter.ts
interface GenerateOptions {
  prompt: string;
  style?: string;
  aspectRatio?: string;
  negativePrompt?: string;
  seed?: number;
  renderingSpeed?: string; // V3 only
  stylePreset?: string;    // V3 only
}

const API_KEY = process.env.IDEOGRAM_API_KEY!;
const USE_V3 = process.env.IDEOGRAM_API_VERSION === "v3";

async function generateImage(options: GenerateOptions) {
  return USE_V3 ? generateV3(options) : generateLegacy(options);
}

// Legacy en

Ideogram Events & Async Patterns

Overview

Ideogram's API is synchronous -- each call blocks until the image is generated (5-15 seconds). For production applications, wrap it in async patterns: job queues for batch generation, callbacks for downstream processing, and pipelines for image post-processing. This skill covers BullMQ queue patterns, callback handlers, and asset processing pipelines.

Prerequisites

• IDEOGRAM_API_KEY configured
• Redis for BullMQ job queue
• Storage for generated images (S3, GCS, or R2)
• Understanding of Ideogram models and style types

Instructions

Step 1: Job Queue for Async Generation

import { Queue, Worker } from "bullmq";
import { writeFileSync, mkdirSync } from "fs";
import { join } from "path";

interface GenerationJob {
  prompt: string;
  style: string;
  aspectRatio: string;
  model: string;
  callbackUrl?: string;
  metadata?: Record<string, string>;
}

const connection = { host: "localhost", port: 6379 };
const imageQueue = new Queue("ideogram-generation", { connection });

// Enqueue a generation job
async function submitGeneration(job: GenerationJob) {
  return imageQueue.add("generate", job, {
    attempts: 3,
    backoff: { type: "exponential", delay: 2000 },
    removeOnComplete: 100,
    removeOnFail: 50,
  });
}

// Worker processes jobs with concurrency limit
const worker = new Worker("ideogram-generation", async (job) => {
  const { prompt, style, aspectRatio, model, callbackUrl, metadata } = job.data;

  // Call Ideogram API (synchronous, blocks 5-15s)
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: {
      "Api-Key": process.env.IDEOGRAM_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image_request: {
        prompt,
        model: model || "V_2",
        style_type: style || "AUTO",
        aspect_ratio: aspectRatio || "ASPECT_1_1",
        magic_prompt_option: "AUTO",
      },
    }),
  });

  if (response.status === 429) {
    throw new Error("Rate limited"); // BullMQ will retry with backoff
  }
  if (!response.ok) {
    throw new Error(`Ideogram API error: ${response.status}`);
  }

  const result = await response.json();
  const image = result.data[0];

  // Download immediately (URLs expire)
  const imgResp = await fetch(image.url);
  const buffer = Buffer.from(await imgResp.arrayBuffer());
  const outputDir = "./generated";
  mkdirSync(outputDir, { recursive: true });
  const filePath = join(outputDir, `${image.seed}.png`);
  writeFileSync(filePath, buffer);

  // Fire callback if provided
  if (callbackUrl) {
    await fetch(callbackUrl, {
      method: &