Skip to main content
ideogram-upgrade-migration Analyze, plan, and execute Ideogram SDK upgrades with breaking change detection.
Use when upgrading Ideogram SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade ideogram", "ideogram migration",
"ideogram breaking changes", "update ideogram SDK", "analyze ideogram version".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill ideogram-upgrade-migration ai automation claude-code devops mcp ai-agents
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/jsonmultipart/form-data
Body format { "image_request": { ... } }FormData fields
Models V_1, V_1_TURBO, V_2, V_2_TURBO, V_2AImplicit V3 (no model field)
Aspect ratio ASPECT_16_916x9
Style types AUTO, GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIMEAUTO, GENERAL, REALISTIC, DESIGN, FICTION
Magic prompt magic_prompt_optionmagic_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, QUALITY50+ style presets : OIL_PAINTING, WATERCOLOR, POP_ART, JAPANDI_FUSION, etc.Style codes : 8-char hex codes for precise style matchingCharacter reference images : Consistent character faces across generationsStyle reference images : Upload style examplesColor palettes with weights : Fine-grained color control
Error Handling Issue Cause Solution RENDER_3D fails in V3Removed from V3 style types Map to GENERAL ANIME fails in V3Renamed to FICTION Update enum mapping JSON body rejected by V3 V3 requires multipart form Switch to FormData magic_prompt_option ignoredV3 uses magic_prompt Update field name model field in V3V3 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.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
