ideogram-upgrade-migration

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 <[e-mail]>
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/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

Instructions

Step 1: Audit Current API Usage

set -euo pipefail
# Find all Ideogram API calls in your codebase
grep -rn  --include= --include= --include= .
grep -rn  --include= --include= .
grep -rn  --include= --include= .
grep -rn  --include= --include= .