ideogram-performance-tuning

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

Model / Speed	Typical Latency	Relative Cost	Quality
V_2_TURBO	3-6s	~$0.05/image	Good
V_2	8-15s	~$0.08/image	High
V3 FLASH	2-4s	Lowest	Draft
V3 TURBO	4-8s	Low	Good
V3 DEFAULT	8-15s	Standard	High
V3 QUALITY	15-25s	Premium	Highest

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)) {
    console.log(`Cache hit: ${key}`);
    return JSON.parse(readFileSync(metaPath, "utf-8"));
  }

  // Generate and cache
  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: style,
        aspect_ratio: aspect,
        magic_prompt_option: "AUTO",
      },
    }),
  });

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

  // Download and cache
  const imgResp = await fetch(image.url);
  const buffer = Buffer.from(await imgResp.arrayBuffer());

  mkdirSync(CACHE_DIR, { recursive: true });
  writeFileSync(imgPath, buffer);
  writeFileSync(metaPath, JSON.stringify({
    ...image,
    localPath: imgPath,
    cachedAt: new Date().toISOString(),
  }));

  return { ...image, localPath: imgPath };
}

Step 3: Parallel Generation with Concurrency Control

import PQueue from "p-queue";

// 8 concurrent (under Ideogram's 10 in-flight limit)
const queue = new PQueue({ concurrency: 8 });

async function parallelGenerate(
  prompts: string[],
  options: { style_type?: string; model?: string } = {}
) {
  const start = Date.now();

  const results = await Promise.all(
    prompts.map(prompt =>
      queue.add(() => cachedGenerate(prompt, options))
    )
  );

  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
  console.log(`Generated ${results.length} images in ${elapsed}s`);
  console.log(`Throughput: ${(results.length / (elapsed as any)).toFixed(2)} img/s`);

  return results;
}

// Generate 20 images -- queue manages concurrency automatically
const prompts = Array.from({ length: 20 }, (_, i) => `Product design variant ${i + 1}`);
await parallelGenerate(prompts, { style_type: "DESIGN", model: "V_2_TURBO" });

Step 4: CDN Upload for Fast Delivery

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });

async function generateWithCDN(prompt: string, options: any = {}) {
  const result = await cachedGenerate(prompt, options);

  // Upload to S3 for CDN delivery
  const key = `ideogram/${result.seed}.png`;
  const buffer = readFileSync(result.localPath);

  await s3.send(new PutObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
    Body: buffer,
    ContentType: "image/png",
    CacheControl: "public, max-age=31536000, immutable",
  }));

  return {
    cdnUrl: `https://${process.env.CDN_DOMAIN}/${key}`,
    seed: result.seed,
    resolution: result.resolution,
  };
}

Performance Tips

1. Use TURBO for drafts -- V_2_TURBO is 2-3x faster than V_2 at lower cost
2. Cache by prompt hash -- identical prompts produce cacheable results
3. Batch with num_images -- 4 images in 1 call is faster than 4 separate calls
4. Download immediately -- URLs expire; download in the same function
5. Set CDN headers -- images are immutable once generated; cache forever
6. Use V3 FLASH for previews -- fastest option for UI thumbnails

Error Handling

Issue	Cause	Solution
Rate limit 429	Concurrency too high	Reduce queue concurrency to 5-8
Slow generation	QUALITY speed or complex prompt	Use TURBO for drafts, simplify prompts
Expired URL	Delayed download	Download immediately in same function
Cache stale	Prompt changed slightly	Normalize prompts before hashing

Output

• Speed-tiered configuration for different use cases
• Prompt-based cache layer preventing duplicate generations
• Parallel generation with concurrency control
• CDN integration for fast image delivery

Resources

• Ideogram API Reference
• p-queue

Next Steps

For cost optimization, see ideogram-cost-tuning.