Ideogram Generation Route Selection

Ideogram Generation Route Selection

Overview

Choose the smallest current generation surface that satisfies latency, transparency, prompt, and model requirements. Make route choice explicit so applications do not inherit stale legacy endpoints or accidentally treat synchronous and asynchronous lifecycles as equivalent.

Prerequisites

• An approved use case, prompt and input classification, latency target, output count, and cost ceiling.
• A server-side key, positive credit, durable storage, and content-review policy.
• Current endpoint-specific documentation; generic examples do not override route contracts.

Current Contract

Ideogram documents V4 synchronous /v1/ideogram-v4/generate, V4 asynchronous /v1/ideogram-v4/async/generate, transparent variants, and P-Image sync/async routes. V4 accepts either text or structured JSON prompting; JSON prompting disables magic prompt. V4 FLASH currently returns 400.

Authentication

Send the server-side IDEOGRAM_API_KEY only through the Api-Key header to https://api.ideogram.ai. Never expose the key or direct paid-generation authority to a browser or untrusted tenant.

Instructions

1. Classify whether the workload requires V4, transparency, P-Image, structured prompting, or compatibility with an existing V3 flow.
2. Choose synchronous handling only when the request deadline safely includes generation and immediate download; otherwise choose async.
3. Build the exact endpoint-specific multipart payload and reject mutually exclusive or unsupported fields before sending.
4. Bound output count, input size, rendering option, in-flight concurrency, and total operation deadline.
5. Validate safety on every returned image and persist approved assets immediately because vendor URLs expire.
6. For async work, persist generation_id, reconcile webhook and polling results idempotently, and close only on a recognized terminal state.
7. Record route, policy, spend, safety, storage, and cleanup evidence without retaining content.

Tool Discipline

Use Read, Glob, and Grep to inspect product requirements, adapters, and fixtures. Use Write and Edit for approved implementation or documentation changes. Do not perform live generation, upload customer content, or alter production traffic by invocation alone.

Approval Boundaries

Require approval for paid calls, sensitive prompts or images, external publication, model or rendering changes, copyright-detection policy changes, and production rollout. A route migration needs a canary and reversible traffic control.

Error Handling