Ideogram Image Transformation Routing
Overview
Map a requested image change to the narrowest current Ideogram operation. Keep edit, remix, structured description, prompt assistance, and outcome-focused tools distinct so rights, uploaded bytes, model control, and output review remain visible.
Prerequisites
- Proven rights to process the input and an approved purpose, destination, and retention period.
- Input validation for supported image type, size, dimensions, and any required mask.
- A server-side key, positive credit, content policy, and durable asset store.
Current Contract
Current surfaces include V4 edit with prompt, V4 remix, V4 describe into a structured JSON prompt, V4 magic prompt, V3 edit/remix, and tools for background removal or replacement, object or logo removal, reframe, ad resize, colorways, material swap, upscale, and text layerization. Outcome-focused tools may choose the model; use model endpoints when direct model control is required.
Authentication
Send IDEOGRAM_API_KEY as Api-Key only from a trusted server to https://api.ideogram.ai. Do not log the key, source image, mask, prompt, structured description, output URL, or generated bytes.
Instructions
- Verify input ownership, consent, data class, permitted transformation, destination, and deletion deadline.
- Choose describe for a reusable V4 structured prompt, edit for localized prompt-guided change, remix for variation, or a named tool for its specific outcome.
- Validate uploaded type and byte limit before the API boundary; V4 describe accepts JPEG, PNG, or WebP up to 25 MB.
- Build only the selected endpoint's multipart fields and set bounded deadlines, outputs, and concurrency.
- Validate transport, schema,
is_image_safe, and expected tool outcome before publishing or chaining work. - Download approved output immediately, store it under an opaque key, and delete temporary input and URL metadata.
- Record rights, route, safety, storage, and cleanup receipts without copying content.
Tool Discipline
Use Read, Glob, and Grep to inspect upload validation, route selection, storage, and fixtures. Use Write and Edit only for approved code or documentation. Do not upload, transform, publish, or retain an image merely because the skill was invoked.
Approval Boundaries
Require accountable approval for biometric, confidential, licensed, customer, or regulated imagery; logo removal; external publication; copyright-detection policy changes; model changes; or durable retention. Decline ambiguous rights rather than attempting a transform.
Error Handling
- Reject unsupported media, oversized uploads, missing masks, and incompatible fields before spending credit.
- A structured describe result uses normalized
[0,1000]boxes ordered[y_min,x_min,y_max,x_max]; preserve that coordinate contract. - Do not retry unsafe results by automatically weakening or rewriting the policy-sensitive request.
Output
Return selected operation, rights decision, input validation summary, status, safe-output count, opaque identifiers, storage and retention state, review decision, and rollback receipt. Exclude source or output content, prompts, credentials, and URLs.
Examples
- Describe an approved product photo, review the structured prompt, then generate a controlled campaign variant.
- Select background removal for an isolated catalog subject; select V4 edit when the requested change depends on a prompt and mask.
Validation
Test route selection and every rejected input class, compare fields with endpoint docs, verify safety and coordinate handling, and confirm temporary media deletion. A visually plausible output does not prove rights, retention, or route correctness.
Resources
- Current first-party evidence map — use the dated endpoint, webhook, billing, team, and training links as the contract index for this workflow.
- Recheck the endpoint-specific page and current OpenAPI description before relying on an enum, limit, beta feature, or lifecycle claim.
- Record live observations as environment-specific evidence, not as universal vendor guarantees.