Ideogram Upgrade & Migration Skill

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

| Aspect | Legacy (/generate) | V3 (/v1/ideogram-v3/generate) | |--------|---------------------|--------------------------------| | Content-Type | application/json | multipart/form-data | | Body format | { "image_request": { ... } } | FormData fields | | Models | V_1, V_1_TURBO, V_2, V_2_TURBO, V_2A | Implicit V3 (no model field) | | Aspect ratio | ASPECT_16_9 | 16x9 | | Style types | AUTO, GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIME | AUTO, GENERAL, REALISTIC, DESIGN, FICTION | | Magic prompt | magic_prompt_option | magic_prompt | | New in V3 | -- | rendering_speed, style_preset, style_codes, character_reference_images | | Color palette | Preset name or hex array | Same, with weight support |

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 endpoint -- JSON body
async function generateLegacy(options: GenerateOptions) {
  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: { "Api-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      image_request: {
        prompt: options.prompt,
        model: "V_2",
        style_type: options.style ?? "AUTO",
        aspect_ratio: options.aspectRatio ?? "ASPECT_1_1",
        magic_prompt_option: "AUTO",
        negative_prompt: options.negativePrompt,
        seed: options.seed,
      },
    }),
  });
  if (!response.ok) throw new Error(`Legacy generate: ${response.status}`);
  return response.json();
}

// V3 endpoint -- multipart form data
async function generateV3(options: GenerateOptions) {
  const form = new FormData();
  form.append("prompt", options.prompt);
  form.append("style_type", mapStyleToV3(options.style ?? "AUTO"));
  form.append("aspect_ratio", mapAspectRatioToV3(options.aspectRatio ?? "ASPECT_1_1"));
  form.append("magic_prompt", "AUTO");
  form.append("rendering_speed", options.renderingSpeed ?? "DEFAULT");
  if (options.negativePrompt) form.append("negative_prompt", options.negativePrompt);
  if (options.seed) form.append("seed", String(options.seed));
  if (options.stylePreset) form.append("style_preset", options.stylePreset);

  const response = await fetch("https://api.ideogram.ai/v1/ideogram-v3/generate", {
    method: "POST",
    headers: { "Api-Key": API_KEY },
    body: form,
  });
  if (!response.ok) throw new Error(`V3 generate: ${response.status}`);
  return response.json();
}

Step 3: Map Legacy Enums to V3

function mapAspectRatioToV3(legacy: string): string {
  const map: Record<string, string> = {
    "ASPECT_1_1": "1x1",    "ASPECT_16_9": "16x9",  "ASPECT_9_16": "9x16",
    "ASPECT_3_2": "3x2",    "ASPECT_2_3": "2x3",    "ASPECT_4_3": "4x3",
    "ASPECT_3_4": "3x4",    "ASPECT_10_16": "10x16", "ASPECT_16_10": "16x10",
    "ASPECT_1_3": "1x3",    "ASPECT_3_1": "3x1",
  };
  return map[legacy] ?? legacy; // Pass through if already V3 format
}

function mapStyleToV3(legacy: string): string {
  const map: Record<string, string> = {
    "AUTO": "AUTO",
    "GENERAL": "GENERAL",
    "REALISTIC": "REALISTIC",
    "DESIGN": "DESIGN",
    "RENDER_3D": "GENERAL",  // No V3 equivalent -- use GENERAL
    "ANIME": "FICTION",      // V3 renamed to FICTION
  };
  return map[legacy] ?? "GENERAL";
}

Step 4: Feature Flag Rollout

// Gradual migration with feature flag
function shouldUseV3(userId?: string): boolean {
  // Phase 1: Internal testing
  if (process.env.IDEOGRAM_FORCE_V3 === "true") return true;

  // Phase 2: Percentage rollout
  if (userId) {
    const hash = Array.from(userId).reduce((h, c) => h * 31 + c.charCodeAt(0), 0);
    const percentage = parseInt(process.env.IDEOGRAM_V3_PERCENTAGE ?? "0");
    return (Math.abs(hash) % 100) < percentage;
  }

  return false;
}

Step 5: Validate Migration

// Run both endpoints and compare results
async function validateMigration(prompt: string) {
  const [legacy, v3] = await Promise.all([
    generateLegacy({ prompt, style: "REALISTIC", aspectRatio: "ASPECT_16_9" }),
    generateV3({ prompt, style: "REALISTIC", aspectRatio: "ASPECT_16_9" }),
  ]);

  console.log("Legacy:", { resolution: legacy.data[0].resolution, seed: legacy.data[0].seed });
  console.log("V3:", { resolution: v3.data[0].resolution, seed: v3.data[0].seed });
  console.log("Both returned images:", legacy.data.length > 0 && v3.data.length > 0);
}

V3 Exclusive Features

After migration, you gain access to:

Rendering speed: FLASH, TURBO, DEFAULT, QUALITY
50+ style presets: OIL_PAINTING, WATERCOLOR, POP_ART, JAPANDI_FUSION, etc.
Style codes: 8-char hex codes for precise style matching
Character reference images: Consistent character faces across generations
Style reference images: Upload style examples
Color palettes with weights: Fine-grained color control

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | RENDER_3D fails in V3 | Removed from V3 style types | Map to GENERAL | | ANIME fails in V3 | Renamed to FICTION | Update enum mapping | | JSON body rejected by V3 | V3 requires multipart form | Switch to FormData | | magic_prompt_option ignored | V3 uses magic_prompt | Update field name | | model field in V3 | V3 has no model field | Remove from V3 requests |

Output

Adapter supporting both legacy and V3 endpoints
Enum mapping functions for breaking changes
Feature flag for gradual rollout
Validation script comparing both endpoints

Resources

Next Steps

For CI integration during upgrades, see ideogram-ci-integration.

Agent Skills: Ideogram Upgrade & Migration

Install this agent skill to your local

Skill Files