ideogram-upgrade-migration

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

• Legacy Generate API
• V3 Generate API
• Ideogram 3.0 Features

Next Steps

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