Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/ideogram-performance-tuning/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill ideogram-performance-tuning. Copyright stays with the author (MIT).

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)) {
    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

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

Prerequisites

• Baseline latency/quota metrics, synthetic prompt fixture revision, error budget, and rollback revision for cache, concurrency, and retry policy.

Examples

env=sandbox; p95=420ms->310ms; concurrency=2; quota=within-budget; rights=test-owned; destination=approved; output_retention=none; rollback=perf-r3 documents a safe canary.

Resources

• Ideogram API Reference
• p-queue

Next Steps

For cost optimization, see ideogram-cost-tuning.