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".
インストールへ移動 Skills Marketplace コミュニティが作成したAIスキルを発見・探索
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill ideogram-upgrade-migrationコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Zipをダウンロード ダウンロード中... このリポジトリの他の Skills 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".
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.
