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 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill ideogram-upgrade-migration命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... jeremylongshore
jeremylongshore/claude-code-plugins-plus-skills
打开 GitHub 仓库 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.
