From ideogram-pack
Migrates Ideogram API from legacy V1/V2 to V3 endpoints by auditing code, detecting breaking changes in formats/models/parameters, and creating version adapters.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin ideogram-packThis skill is limited to using the following tools:
!`npm list 2>/dev/null | head -10`
Migrates image generation code from DALL-E, Midjourney, Stable Diffusion to Ideogram API. Audits integrations via grep/Bash, maps endpoints for JS/TS/Python using strangler fig pattern.
Implements low-downtime API migrations between versions or frameworks using strangler fig, traffic shadowing, endpoint mapping, adapters, and phased cutovers.
Plans and executes Canva Connect API upgrades, detects breaking changes, migrates brand template IDs, and adapts to endpoint deprecations like comment API.
Share bugs, ideas, or general feedback.
!npm list 2>/dev/null | head -10
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.
| 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 |
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" .
// 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();
}
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";
}
// 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;
}
// 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);
}
After migration, you gain access to:
FLASH, TURBO, DEFAULT, QUALITYOIL_PAINTING, WATERCOLOR, POP_ART, JAPANDI_FUSION, etc.| 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 |
For CI integration during upgrades, see ideogram-ci-integration.