First Ideogram V4 Generation

Overview

Prove the smallest current Ideogram integration: one server-side multipart request, one checked response, and immediate persistence of any returned image. Keep the smoke test bounded because the call spends prepaid credit and response URLs expire.

Prerequisites

• An approved IDEOGRAM_API_KEY, positive API credit, and a non-sensitive prompt.
• Server-side network access and durable storage outside the repository.
• A request deadline, maximum output count, and named spend owner.

Current Contract

The synchronous V4 route is POST /v1/ideogram-v4/generate using multipart/form-data. Supply either text_prompt or json_prompt, never both. Structured JSON prompts disable magic prompt. A result can be present but unsafe, represented by is_image_safe=false and an empty URL.

Authentication

Send IDEOGRAM_API_KEY only as the Api-Key header to https://api.ideogram.ai. Keep the request on a trusted server and never echo the key, prompt, response URL, or image bytes into logs or receipts.

Instructions

1. Confirm the prompt classification, destination, output count, deadline, and approval for a paid live request.
2. Build a multipart body with exactly one prompt form, a supported aspect ratio, and an explicitly reviewed rendering option.
3. Send the request to the V4 synchronous route with the server-side API key and a bounded timeout.
4. Reject non-success status codes and validate the response schema before reading image fields.
5. Check is_image_safe; treat an unsafe item or empty URL as a policy outcome, not a downloadable success.
6. Download an approved image immediately, verify content type and byte limit, and store it under an application-owned opaque identifier.
7. Return content-free request, storage, timing, safety, and cleanup evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect the existing adapter, storage boundary, and fixtures. Use Write and Edit only for approved code, fixture, or documentation changes. Do not run a paid request merely because this skill was selected.

Approval Boundaries

Require approval for live spend, sensitive prompts, customer images, external publication, or durable retention. The smoke test must not overwrite an existing asset; rollback removes only the newly created opaque object and associated test metadata.

Error Handling

• 400 indicates an invalid combination or endpoint-specific option; V4 FLASH is currently not accepted.
• 401, 422, and 429 require authentication, validation, and capacity-specific handling.
• A successful HTTP response with is_image_safe=false must not be retried by mutating the prompt automatically.

Output

Return endpoint, environment, prompt class, HTTP status, output and safe-item counts, opaque generation or request identifiers, durable storage key, latency, cost owner, and rollback status. Exclude raw prompts, credentials, image URLs, and image bytes.

Examples

• Generate a synthetic square label design, persist it to a test bucket, then delete it after assertions.
• Report endpoint=v4-sync; outputs=1; safe=1; persisted=yes; url_retained=no; cleanup=complete.

Validation

Re-run the adapter's deterministic fixture test, verify exactly one prompt form was sent, confirm the URL was not retained, and check storage and deletion receipts. Live output quality alone does not prove schema, safety, or retention 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.