Skip to main content
ideogram-upgrade-migration Migrate between Ideogram API versions (V_1 to V_2 to V3) with breaking change detection.
Use when upgrading from legacy to V3 endpoints, updating model versions,
or handling deprecated API parameters.
Trigger with phrases like "upgrade ideogram", "ideogram migration",
"ideogram v2 to v3", "ideogram breaking changes", "migrate ideogram API".
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill ideogram-upgrade-migrationThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
Related occupations SOC
Based on SOC occupation classification
name ideogram-upgrade-migration description Migrate between Ideogram API versions (V_1 to V_2 to V3) with breaking change detection.
Use when upgrading from legacy to V3 endpoints, updating model versions,
or handling deprecated API parameters.
Trigger with phrases like "upgrade ideogram", "ideogram migration",
"ideogram v2 to v3", "ideogram breaking changes", "migrate ideogram API".
allowed-tools Read, Write, Edit, Bash(npm:*), Grep version 1.10.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","ideogram","api","migration"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
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-dataBody 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_916x9Style types AUTO, GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIMEAUTO, GENERAL, REALISTIC, DESIGN, FICTIONMagic prompt magic_prompt_optionmagic_promptNew in V3 -- rendering_speed, style_preset, style_codes, character_reference_imagesColor palette Preset name or hex array Same, with weight support
Instructions
Step 1: Audit Current API Usage
set -euo pipefail
grep -rn "api.ideogram.ai"
"*.ts"
"*.js"
"*.py"
"ASPECT_"
"*.ts"
"*.js"
"image_request"
"*.ts"
"*.js"
"magic_prompt_option"
"*.ts"
"*.js"
Step 2: Create Adapter for Both Versions
interface GenerateOptions {
prompt : string ;
style ?: string ;
aspectRatio ?: string ;
negativePrompt ?: string ;
seed ?: number ;
renderingSpeed ?: string ;
stylePreset ?: string ;
}
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);
}
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 ();
}
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;
}
function mapStyleToV3 (legacy : string string {
const map : Record <string , string > = {
"AUTO" : "AUTO" ,
"GENERAL" : "GENERAL" ,
"REALISTIC" : "REALISTIC" ,
"DESIGN" : "DESIGN" ,
"RENDER_3D" : "GENERAL" ,
"ANIME" : "FICTION" ,
};
return map[legacy] ?? "GENERAL" ;
}
Step 4: Feature Flag Rollout
function shouldUseV3 (userId ?: string boolean {
if (process.env .IDEOGRAM_FORCE_V3 === "true" ) return true ;
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
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.
