Ideogram Continuous Integration

Overview

Make Ideogram integration quality reproducible without granting untrusted changes a paid credential. Use fixtures and schema checks for every pull request, then isolate any live smoke test behind trusted-branch, synthetic-content, spend, and concurrency controls.

Prerequisites

• CI trust model, branch policy, test runner, adapter seam, and secret provider.
• Sanitized fixtures covering sync, async, safety, errors, webhook, polling, and storage.
• Named owners for schema refresh, live-smoke spend, and failed-run cleanup.

Current Contract

The first-party OpenAPI is machine-readable, while endpoint pages carry important behavioral details such as multipart requirements, unsafe empty URLs, and current V4 rendering constraints. CI must preserve both schema and documented semantic assertions.

Authentication

Pull-request jobs must run without IDEOGRAM_API_KEY. A separately approved live job may receive a short-lived or environment-scoped secret server-side and send it only as Api-Key to https://api.ideogram.ai.

Instructions

1. Inventory workflows, fork behavior, secret exposure, cache artifacts, and existing paid calls.
2. Add offline tests for multipart field names, mutually exclusive prompts, typed errors, safety outcomes, async terminal states, signature verification, download limits, and storage cleanup.
3. Pin a reviewed OpenAPI snapshot or hash and report drift without blindly replacing owned contracts.
4. Scan fixtures and artifacts for keys, prompts, URLs, image bytes, and customer identifiers.
5. Gate any live smoke to a trusted protected context with manual or environment approval, one synthetic request, strict timeout, output count, and cost ceiling.
6. Persist no vendor URL, delete generated test assets, and publish only content-free status evidence.
7. Require offline tests for merge; keep vendor availability from making normal pull requests flaky.

Tool Discipline

Use Read, Glob, and Grep to inspect workflows and tests. Use Write and Edit for approved CI, fixture, and documentation changes. Do not add secrets, enable paid fork jobs, or change required checks without repository authority.

Approval Boundaries

Require approval for workflow permissions, new secret access, live spend, external artifact upload, required-check changes, and branch-protection changes. Fork-originated code must never receive the Ideogram key.

Error Handling

• Fail on fixture secrets, undocumented schema changes, unsafe-output bypass, or retained image artifacts.
• Quarantine vendor outage in the optional live lane; do not weaken deterministic merge gates.
• Cancel timed-out jobs and reconcile any accepted async generation before retrying.

Output

Ideogram Error Diagnosis

Overview

Classify an Ideogram failure before changing code or retrying spend. Separate authentication, billing readiness, request validation, throttling, service capacity, safety policy, asynchronous lifecycle, download expiry, and application storage failures.

Prerequisites

• Endpoint, method, environment, timestamp, sanitized status, and opaque request or generation identifier.
• The exact adapter version and current endpoint documentation.
• Access to content-free logs, fixtures, queue state, and storage receipts.

Current Contract

Endpoint docs surface 400, 401, 422, and 429; operational paths can also encounter transient service failures such as 503. V4 FLASH currently produces 400. Unsafe generation may complete with is_image_safe=false and an empty URL. Async work must reach a recognized terminal state.

Authentication

Verify only that a server-side Api-Key header is configured for https://api.ideogram.ai; never paste or print its value. A key, team balance, and application user authorization are separate checks.

Instructions

1. Capture the endpoint, status, latency, attempt count, content type, sanitized error code, and opaque identifiers.
2. Reproduce against a fixture before considering another paid live call.
3. Map 401 to key presence, header name, environment, and revocation; map 400 or 422 to endpoint-specific fields and media validation.
4. Map 429 to local in-flight concurrency, queue deadline, and server retry guidance; map 503 or transport failure to bounded transient handling.
5. Inspect is_image_safe, URL presence, async terminal state, download timing, and durable-storage result separately.
6. Apply one minimal correction, rerun the deterministic test, and use one approved synthetic live probe only if needed.
7. Record cause, evidence, spend, affected scope, correction, and rollback.

Tool Discipline

Use Read, Glob, and Grep for adapters, schemas, logs, and fixtures. Use Write and Edit only for an approved minimal fix or test. Do not rotate keys, add credit, replay production requests, alter prompts, or relax safety automatically.

Approval Boundaries

Require ownership before a paid reproduction, credential rotation, balance change, concurrency increase, policy change, customer-content access, or production deploy. Preserve the failed state until enough sanitized evidence exists.

Error Handling

• Never retry 400, 401, or 422 without a verified correction.
• Retry transient capacity failures only within attempt, jitter, and total-deadline bou…

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

• Reject V4 FLASH until endpoint documentation states support.
• Treat 400, 401, 422, an…

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

1. Verify input ownership, consent, data class, permitted transformation, destination, and deletion deadline.
2. 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.
3. Validate uploaded type and byte limit before the API boundary; V4 describe accepts JPEG, PNG, or WebP up to 25 MB.
4. Build only the selected endpoint's multipart fields and set bounded deadlines, outputs, and concurrency.
5. Validate transport, schema, is_image_safe, and expected tool outcome before publishing or chaining work.
6. Download approved output immediately, store it under an opaque key, and delete temporary input and URL metadata.
7. 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 norma…

Ideogram Cost Governance

Overview

Control prepaid Ideogram consumption without embedding prices that can drift. Tie admission to an accountable budget, choose the narrowest route, bound outputs and retries, and measure durable safe results rather than HTTP success or generated candidates.

Prerequisites

• Team billing owner, current balance source, budget period, workload owner, and quality floor.
• Request volume, endpoint and rendering mix, output count, retry rate, unsafe rate, and storage failures.
• A current pricing review from the first-party API pricing page.

Current Contract

Ideogram API billing is separate from the web application, requires positive prepaid credit, and can use auto-recharge. Keys in one team share credits and billing, so per-key usage is not a separate vendor balance. Prices and recharge choices are time-sensitive and must be verified rather than copied into this skill.

Authentication

Workers use server-side IDEOGRAM_API_KEY as Api-Key to https://api.ideogram.ai. Cost evidence may include team, endpoint, request, and opaque generation identifiers, but not the key, prompts, images, or URLs.

Instructions

1. Retrieve current first-party pricing and balance behavior, recording date, currency, unit, and owner.
2. Inventory demand by tenant, use case, route, rendering option, output count, retry class, safety result, and durable-storage result.
3. Define request, tenant, daily, campaign, and incident ceilings with fail-closed admission.
4. Choose the least costly route that still meets model, quality, transparency, edit, or tool requirements.
5. Prevent duplicate paid work by persisting async identifiers, bounding retries, expiring stale queue items, and deduplicating callers.
6. Attribute spend to useful safe assets that reached durable storage; surface unsafe, failed, abandoned, and expired-URL waste separately.
7. Canary each tuning change and retain a quality, safety, latency, and rollback comparison.

Tool Discipline

Use Read, Glob, and Grep for billing adapters, queues, metrics, and fixtures. Use Write and Edit for approved budgets, tests, or documentation. Do not add credit, enable auto-recharge, change prices, or run paid experiments by invocation alone.

Approval Boundaries

Require owners for balance additions, recharge settings, budget changes, lower-quality routes, deleted queued work, paid benchmarks, and production rollout. Cost reduction cannot override safety, rights, or retention policy.

Error Handling

• Stop admission before balance exhaustion; repeated failures are not a budget strategy.
• Do not retry validation, auth, unsafe, or already accepted async work automatically.
• An image that was never durably stored is waste even if generation suc…

Ideogram Data Lifecycle

Overview

Map and enforce the lifecycle of every datum that crosses an Ideogram workflow. Distinguish prompts, JSON descriptions, source media, masks, generated outputs, temporary links, safety decisions, metadata, logs, and custom-training assets because each has different ownership and retention needs.

Prerequisites

• Use case, data owner, tenant, classification, rights basis, region, retention, and deletion SLO.
• Architecture for upload, API, async state, webhook, polling, download, storage, review, publication, backup, and telemetry.
• Vendor terms and privacy review appropriate to the workload.

Current Contract

V4 describe can transform an uploaded image into a structured json_prompt; its bounding boxes use normalized [0,1000] coordinates in [y_min,x_min,y_max,x_max] order. Output URLs expire. Custom training supports datasets of 10–100 images, optional captions or ZIP upload, model training, and model-status retrieval.

Authentication

Keep IDEOGRAM_API_KEY outside data stores and send it only as Api-Key from a trusted server. Application authorization must bind every input, generated object, dataset, and trained-model reference to its tenant and purpose.

Instructions

1. Inventory each data class, source, purpose, rights basis, vendor transmission, destination, readers, retention, and deletion path.
2. Minimize prompts and metadata, validate image type and size, strip unnecessary metadata, and isolate temporary files.
3. Store async identifiers and safety decisions without copying content into queues, logs, traces, or incident evidence.
4. Download approved output promptly, validate it, store under an opaque tenant-scoped key, and discard the vendor URL.
5. Apply separate governance to describe output, captions, datasets, ZIPs, custom model references, backups, and derived assets.
6. Enforce access, encryption, publication review, lifecycle deletion, legal holds, and tenant export.
7. Test deletion across primary storage, metadata, queue, cache, backup policy, and custom-training records.

Tool Discipline

Use Read, Glob, and Grep to inspect schemas, stores, policies, and fixtures. Use Write and Edit for approved lifecycle controls or documentation. Do not open, copy, upload, publish, or delete customer media without authority.

Approval Boundaries

Require data-owner approval for sensitive inputs, training, new purposes, longer retention, external publication, cross-region movement, backup exceptions, and destructive deletion. Rights uncertainty is a stop condition.

Error Handling

• Never treat an expiring URL as durable storage or an authorization token.
• Quarantine tenant-mismatched, malformed, oversized, or unexpectedly content-bear…

Ideogram Sanitized Debug Bundle

Overview

Create the minimum diagnostic package needed to reproduce or escalate an Ideogram problem. Preserve endpoint, schema, status, timing, concurrency, async, safety, and storage facts while excluding the content and credentials that commonly leak through generic support archives.

Prerequisites

• An incident identifier, bounded time window, affected environment, and bundle recipient.
• Approved local evidence locations and a data-classification owner.
• A redaction policy, maximum bundle size, retention deadline, and deletion owner.

Current Contract

Useful content-free fields include endpoint family, method, deployment SHA, adapter version, HTTP status, sanitized vendor error class, generation_id, async state, is_image_safe, URL-present boolean, queue depth, in-flight count, latency, and object-store result. Prompts, uploaded media, generated images, keys, and expiring URLs are not required by default.

Authentication

Represent authentication as booleans and provenance such as header_present=true and secret_source=production-manager. Never collect the Api-Key value, environment dumps, shell history, request headers, or secret-manager payloads.

Instructions

1. Define the incident, window, recipient, evidence roots, permitted fields, byte ceiling, and deletion deadline.
2. Use an allowlist schema rather than copying full logs, requests, responses, or environment state.
3. Collect version, endpoint, status, timing, concurrency, queue, safety, polling or webhook, and storage facts.
4. Replace user, object, request, and generation identifiers with stable incident-local tokens unless the recipient explicitly requires an opaque vendor ID.
5. Scan the staged bundle for credential patterns, prompts, URLs, image signatures, EXIF, binary files, and customer identifiers.
6. Write a manifest with hashes, field provenance, redaction counts, limitations, owner, and expiry.
7. Obtain recipient approval, transfer through the approved channel, and record deletion.

Tool Discipline

Use Read, Glob, and Grep to locate and inspect the approved evidence scope. Use Write and Edit only inside the explicitly named staging directory and manifest. Do not run live calls, expand the time window, scrape home directories, or attach repository secrets.

Approval Boundaries

Require approval before including raw vendor bodies, opaque production identifiers, customer-derived metadata, or any content. The recipient and expiry must be known before transfer; bundle creation alone does not authorize sharing.

Error Handling

• Stop if an allowlist field cannot be separated from prompt or image content.
• Reject archives containing IDEOGRAM_API_KEY, …

Ideogram Deployment Boundary

Overview

Deploy Ideogram behind an application-owned server, queue, safety policy, and durable object store. Match runtime deadlines to sync or async behavior, keep paid authority out of clients, and preserve a reversible traffic path.

Prerequisites

• Frozen release SHA, platform owner, environment, traffic slice, SLO, and rollback target.
• Secret manager, queue or concurrency control, object storage, monitoring, and incident response.
• Positive credit, billing owner, approved synthetic canary, and retention policy.

Current Contract

Ideogram calls use https://api.ideogram.ai; default capacity is 10 in-flight requests. Async routes return generation_id and support webhook delivery with polling fallback. Image URLs expire, so deployment must download validated outputs into application storage before acknowledging durable completion.

Authentication

Inject IDEOGRAM_API_KEY into the server or worker identity and send it only as Api-Key. A public browser receives application-scoped authorization, never the vendor credential or direct vendor URL.

Instructions

1. Map request ingress, tenant auth, validation, queue, Ideogram route, webhook, polling, download, safety, storage, and publishing boundaries.
2. Choose sync only when platform and request deadlines safely cover generation plus download; otherwise persist async state.
3. Configure account-level concurrency below verified capacity, bounded queues, retry deadlines, and graceful drain.
4. Inject secrets by runtime reference, restrict egress to the approved host, and prevent request or response body logging.
5. Validate safety and media type before writing an opaque tenant-scoped object; discard temporary URLs.
6. Deploy a synthetic canary, compare status, latency, storage, safety, and cost signals, then increase traffic gradually.
7. Roll back traffic and reconcile in-flight generations and objects before terminating the prior version.

Tool Discipline

Use Read, Glob, and Grep for manifests, infrastructure, adapters, and evidence. Use Write and Edit only for approved deployment changes. Invocation does not authorize a deploy, secret mutation, credit purchase, traffic shift, or destructive cleanup.

Approval Boundaries

Require explicit approval for production secret access, new egress, live spend, policy changes, storage retention, traffic shifting, and rollback. Preserve the previous deployable artifact until in-flight work is reconciled.

Error Handling

• Stop rollout on secret exposure, rising 429, lost async state, unsafe-publication paths, or storage failure.
• Do not declare success while assets exist only at expiring vendor URLs.
• Drain or cancel local queue work before rol…

Ideogram Enterprise Access Control

Overview

Keep Ideogram team administration distinct from application authorization. Vendor roles govern a shared team boundary, while the application must enforce tenant, use-case, spend, upload, generation, review, publication, retention, and incident permissions.

Prerequisites

• Ideogram team inventory, role holders, keys, billing owner, environments, and emergency contacts.
• Application identity provider, tenant model, service identities, permission catalog, and audit requirements.
• Joiner, mover, leaver, key rotation, access review, and break-glass processes.

Current Contract

Ideogram documents Owner, Admin, and Member team roles. Team members share keys, credits, and billing context; separate keys do not inherently provide per-user or per-environment vendor budgets. Avoid inventing finer Ideogram permissions that the application must actually enforce.

Authentication

Store each server-side IDEOGRAM_API_KEY in the approved secret manager and send it only as Api-Key to https://api.ideogram.ai. Users authenticate to the application; only constrained service identities reach the vendor adapter.

Instructions

1. Inventory vendor role holders, keys, credit authority, environments, application roles, service identities, and asset stores.
2. Define vendor Owner, Admin, and Member responsibilities from current first-party documentation.
3. Build an application permission matrix for request, upload, transform, train, spend, review, publish, export, delete, key administration, and incident actions.
4. Enforce tenant and environment scope at the gateway, queue, async state, webhook, storage, and publisher.
5. Separate requester, approver, publisher, billing administrator, key administrator, and auditor where risk warrants.
6. Test denied access, cross-tenant object access, wrong-environment key use, leaver removal, key rotation, and break-glass expiry.
7. Record periodic review evidence and remediate stale identities or excessive service authority.

Tool Discipline

Use Read, Glob, and Grep for manifests, policy, identity mappings, and audit evidence. Use Write and Edit for approved policy or tests. Do not change team members, roles, keys, billing, or production identities by invocation alone.

Approval Boundaries

Require authorized administrators for vendor membership, role, key, and billing changes. Require application and data owners for tenant permissions, publication, retention, and deletion. Break-glass access must expire and be reviewed.

Error Handling

• Do not claim application permissions are enforced by a coarse vendor team role.
• Revoke or rotate authority after a leaver or credible key exposure, then verify every consumer.
• Deny ambiguous te…

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 …

Ideogram Incident Response

Overview

Stabilize an Ideogram integration before chasing image quality or replaying paid requests. Preserve evidence, reduce blast radius, reconcile accepted work, protect sensitive media, and choose recovery actions by incident class.

Prerequisites

• Incident commander, environment, start time, impact statement, and communication channel.
• Read access to content-free application, queue, vendor-status, webhook, polling, storage, and billing evidence.
• Known controls for admission, concurrency, key revocation, traffic rollback, queue drain, and publication stop.

Current Contract

Incidents commonly cross separate boundaries: server-side Api-Key, prepaid shared team credit, default in-flight capacity, async generation_id, signed but non-guaranteed webhook delivery, item safety, expiring URLs, and application storage. Recovery must not collapse these into a generic retry.

Authentication

Never paste the API key into incident chat or commands. Verify secret provenance through metadata; if exposure is credible, stop new traffic, revoke under owner approval, rotate consumers, and audit historical leakage.

Instructions

1. Declare severity, impact, affected environment and tenants, known time window, and incident commander.
2. Freeze risky deployments and broad retries; preserve sanitized statuses, identifiers, queue state, and storage receipts.
3. Classify credential, depleted credit, validation, 429 pressure, vendor capacity, unsafe publication, webhook loss, expired URL, or storage failure.
4. Contain with the smallest control: close admission, reduce concurrency, stop publishing, switch to polling, isolate storage, or roll back traffic.
5. Reconcile every accepted async identifier before resubmission and prevent duplicate asset publication.
6. Recover with synthetic canaries, then restore bounded traffic while monitoring safety, durable completion, errors, latency, and spend.
7. Record timeline, decisions, evidence, customer impact, cleanup, follow-ups, and final state.

Tool Discipline

Use Read, Glob, and Grep for evidence and known runbooks. Use Write and Edit for approved incident records or fixes. Do not revoke keys, add credit, delete assets, replay jobs, or deploy without incident authority.

Approval Boundaries

The incident commander approves containment and restoration; security owns credential response, billing owns credit, moderation owns unsafe publication, and data owners approve asset access or deletion. Separate reversible mitigation from destructive action.

Error Handling

• Do not regenerate solely because a vendor URL expired; confirm rights, budget, and absence of durable copy.
• Do not increase concurrency during 429 pressure.
…

Ideogram Authentication and Installation

Overview

Establish a reviewable Ideogram API boundary before any paid generation runs. Separate developer-account enrollment, team ownership, billing, secret storage, and application authorization so a valid key never becomes accidental authority for a browser or untrusted tenant.

Prerequisites

• A named Ideogram team Owner and accountable application owner.
• Accepted developer terms, a payment method, and positive prepaid API credit.
• A server-side secret manager and an environment-specific rollback plan.

Current Contract

Ideogram API subscriptions and web-app subscriptions are billed separately. Keys are created in the API dashboard, displayed once, revocable, and shared against the team's credit balance. Team roles are Owner, Admin, and Member; multiple keys do not create separate balances.

Authentication

Store the key as IDEOGRAM_API_KEY and send it only in the Api-Key header to https://api.ideogram.ai. Never place it in source control, URLs, browser bundles, prompts, logs, screenshots, or client telemetry. Treat application user authorization as a separate control.

Instructions

1. Inventory the runtime, Ideogram team, environment, data class, expected concurrency, and spend owner.
2. Confirm developer terms, payment method, positive credit, and the team role allowed to create or revoke keys.
3. Create one environment-scoped key and capture it directly into the approved secret manager because it is shown once.
4. Configure the API host and secret reference without copying the value into repository files.
5. Validate configuration offline, then run one synthetic generation only when live spend and content are approved.
6. Record the key owner, creation date, rotation route, billing owner, validation result, and rollback state.

Tool Discipline

Use Read, Glob, and Grep to inspect dependency, configuration, and deployment surfaces. Use Write and Edit only for approved configuration or documentation changes. Invocation alone does not authorize key creation, billing changes, team membership changes, paid generation, or deployment.

Approval Boundaries

Require explicit ownership before adding credit, enabling auto-recharge, creating or revoking a key, changing a team role, sending sensitive prompts or images, or deploying a live integration. Repository inspection and synthetic offline validation remain read-only.

Error Handling

• A 401 points first to a missing, malformed, revoked, or wrong-environment key.
• A syntactically valid key can still fail when the shared team balance lacks positive credit.
• A key exposed to a client or log is an incident: revoke it, rotate consumers, and verify removal from history.

Output

Ideogram Fixture-First Development Loop

Overview

Develop the Ideogram boundary against owned request and response contracts before spending credit. Model multipart fields, asynchronous lifecycle states, unsafe outputs, transient errors, and expiring URLs as fixtures so the fast loop remains deterministic and privacy-safe.

Prerequisites

• The repository's adapter seam, test runner, fixture policy, and data classification.
• Sanitized synthetic examples for success, unsafe output, validation failure, throttling, and terminal failure.
• An opt-in live-smoke flag that is disabled by default and on untrusted forks.

Current Contract

Current generation surfaces include V4 synchronous and asynchronous routes, transparent variants, P-Image, and V3 compatibility routes. Async work returns a generation_id; status is reconciled by appending that returned value to GET /v1/generations/ or by receiving a webhook. Returned asset URLs are temporary.

Authentication

Fixtures must not contain credentials. When a separately approved live lane runs, inject IDEOGRAM_API_KEY server-side and send it only in the Api-Key header to the configured first-party host.

Instructions

1. Read the adapter and enumerate request fields, response variants, error classes, and storage side effects.
2. Create sanitized fixtures for sync success, async submission, in-progress polling, safe and unsafe completion, 400, 401, 422, 429, and 503.
3. Test multipart construction by field name and file metadata without snapshotting secrets or customer content.
4. Verify idempotent status reconciliation, duplicate webhook handling, bounded polling, URL download, and durable object persistence.
5. Keep the paid live smoke behind an explicit environment flag, trusted context, credit ceiling, and synthetic prompt.
6. Compare live response shape to fixtures, update only reviewed schema drift, and record cleanup.

Tool Discipline

Use Read, Glob, and Grep to locate adapters, fixtures, and test commands. Use Write and Edit for approved test and adapter changes. Do not infer permission to call Ideogram, upload an image, spend credit, or retain generated media.

Approval Boundaries

Offline fixture work is safe by default. Require approval before any live request, use of production credentials, customer-derived input, shared bucket write, fixture refresh from real responses, or deployment.

Error Handling

• Reject fixtures containing key-like values, raw customer prompts, image bytes, or live URLs.
• Keep retry tests deterministic by injecting clocks and jitter rather than sleeping.
• Treat unrecognized response fields as explicit drift evidence; do not silently discard …

Ideogram Production Migration

Overview

Modernize a complete Ideogram image workflow without assuming endpoint names imply equivalent semantics. Inventory legacy and V3 behavior, select V4, P-Image, or outcome-focused tools by requirement, compare safe durable results, and preserve in-flight state and rollback.

Prerequisites

• Source routes, payloads, traffic, consumers, stored assets, async state, quality rubric, and owners.
• Target use cases, model-control needs, latency, safety, rights, cost, and retention constraints.
• Feature flags, shadow destination, reconciliation plan, canary budget, and rollback window.

Current Contract

First-party navigation labels /generate, /edit, /remix, /reframe, and /describe as Legacy Endpoints. Current surfaces include V3, V4 sync/async/transparent, P-Image, edit, remix, structured describe, magic prompt, outcome-focused tools, and custom training. Payload and rendering semantics differ.

Authentication

Preserve the server-side Api-Key boundary and environment isolation throughout migration. Dual-run fixtures and receipts must exclude keys, prompts, uploaded images, generated assets, and temporary URLs.

Instructions

1. Inventory each source route, field, enum, output, error, retry, safety, storage, consumer, and in-flight state.
2. Classify every use case by required model control, transparency, edit semantics, structured prompting, specialized outcome, latency, and cost.
3. Select a documented target route for each use case; record non-equivalence and retire unsupported assumptions.
4. Build owned translation at the application boundary instead of leaking mixed legacy and target schemas to consumers.
5. Compare sanitized fixtures, then run approved shadow or dual generation into isolated storage without double publication.
6. Evaluate transport, safety, useful quality, latency, cost, URL persistence, async reconciliation, and deletion.
7. Canary by tenant or use case, reconcile every known generation and asset, then remove legacy traffic only after the rollback window.

Tool Discipline

Use Read, Glob, and Grep for routes, consumers, schemas, state, and evidence. Use Write and Edit for approved migration code, tests, and records. Do not dual-run paid customer traffic or delete legacy assets by invocation alone.

Approval Boundaries

Require owners for target selection, model or quality changes, dual-run spend, customer-derived content, safety differences, cutover, and destructive retirement. A migration with no state and asset reconciliation plan is not ready.

Error Handling

• Do not map legacy enums or rendering speed by string similarity.
• Stop on unexplained safety, output-count, aspect, storage, or quality diver…

Ideogram Environment Isolation

Overview

Prevent development and staging activity from consuming production authority or contaminating production media. Separate keys, application identities, budgets, routes, queues, state, storage, telemetry, and cleanup while recognizing that keys in the same Ideogram team share credits.

Prerequisites

• Environment inventory, Ideogram team model, billing owner, and promotion owner.
• Secret, queue, webhook, storage, observability, data, and retention maps.
• A synthetic test-data policy and production-access exception process.

Current Contract

Ideogram supports multiple revocable keys, but keys within one team share credit and billing. Team roles are Owner, Admin, and Member. Environment separation therefore needs application-owned budgets and controls even when separate vendor keys use one shared team.

Authentication

Create distinct secret references per environment and inject each server-side as Api-Key to https://api.ideogram.ai. Never copy a production key into developer machines, pull-request jobs, staging configuration, or shared examples.

Instructions

1. Inventory each environment's key reference, team, role owner, budget, route, queue, webhook URL, storage prefix, telemetry, and data class.
2. Assign distinct keys where supported and document the shared-credit boundary of any common Ideogram team.
3. Enforce application-side environment and tenant budgets, concurrency, and destination allowlists.
4. Use environment-specific webhook hosts and bind every delivery to a known generation, tenant, and environment.
5. Isolate object stores or prefixes, signing keys, retention jobs, and publication targets.
6. Promote immutable code and schema evidence, not prompts, images, URLs, credentials, or in-flight state.
7. Test wrong-key, wrong-webhook, wrong-bucket, and cross-environment access denial plus independent rollback.

Tool Discipline

Use Read, Glob, and Grep to inspect configuration and infrastructure. Use Write and Edit for approved environment definitions or tests. Do not create keys, copy secrets, add credit, or mutate deployments without the relevant owner.

Approval Boundaries

Require approval for production access, shared team or balance use, role changes, secret creation or revocation, data copying, external publication, and deployment. Treat emergency production access as time-bounded and auditable.

Error Handling

• A distinct key does not imply a distinct vendor balance.
• Reject callbacks and objects whose recorded environment differs from the receiver or storage boundary.
• Revoke a key copied across environments and verify all consumers before restoration.

Output

Return an environment matrix of key references, shared billin…

Ideogram Observability

Overview

Measure whether accepted image work becomes a safe durable asset within its deadline and budget. Join application request, queue, vendor, webhook or polling, download, storage, and publication stages using opaque identifiers rather than prompts or media.

Prerequisites

• Service boundaries, SLO, error budget, budget window, owners, and incident thresholds.
• A data dictionary and cardinality policy for metrics, logs, and traces.
• Known endpoint, queue, async state, safety, storage, and cleanup transitions.

Current Contract

Useful vendor-facing signals include endpoint family, HTTP status, generation_id, async state, is_image_safe, URL-present boolean, and timing. Default capacity is 10 in-flight requests, while actual account behavior and current pricing must be observed at decision time.

Authentication

Telemetry must record only that server-side Api-Key authentication was configured or rejected. Never capture the header value, prompts, structured prompts, source images, output images, signed URLs, or raw payload bodies.

Instructions

1. Define the user outcome as a safe approved asset durably stored by its deadline, not merely HTTP 200.
2. Instrument admission, queue wait and age, in-flight count, upload, generation, webhook, polling, download, validation, storage, review, and cleanup stages.
3. Count statuses by endpoint and environment; separate auth, validation, throttling, capacity, safety, expiry, and storage failures.
4. Track accepted async generations to one terminal state and alert on stuck, duplicate, missing-webhook, or unreconciled records.
5. Attribute estimated or reconciled spend to useful, unsafe, failed, abandoned, and unstored outcomes.
6. Build SLO dashboards and actionable alerts with owners, runbook links, burn windows, and content-free exemplars.
7. Test alert delivery and verify telemetry deletion and access controls.

Tool Discipline

Use Read, Glob, and Grep to inspect instrumentation, dashboards, and logs. Use Write and Edit for approved telemetry or runbook changes. Do not query raw customer content, enable body capture, or change production sampling without authority.

Approval Boundaries

Require review for new labels, retained opaque IDs, cross-tenant joins, sampling, external telemetry export, SLO changes, and production deployment. High-cardinality content fields are prohibited by default.

Error Handling

• Alert on rising 429 before retry traffic amplifies it.
• Distinguish unsafe output from transport failure and expired URL from generation failure.
• Treat missing durable-storage confirmation as incomplete even when the vendor stage succeeded.

Output

Return metric and trace sc…

Ideogram Performance Tuning

Overview

Improve end-to-end time and useful throughput with measurements, not unsupported rendering flags. Separate queue wait, upload, vendor generation, webhook or polling, download, validation, and storage so optimization preserves safety, quality, cost, and asset durability.

Prerequisites

• Representative synthetic workload, latency and throughput SLOs, quality floor, and cost ceiling.
• Per-stage metrics, current endpoint mix, output count, media sizes, and concurrency policy.
• Approved benchmark budget, isolated destination, and cleanup owner.

Current Contract

Ideogram offers synchronous and asynchronous routes plus V4, transparency, P-Image, V3, and outcome-focused tools. Route-specific rendering options differ; V4 FLASH currently returns 400. Default capacity is 10 in-flight requests, and returned asset URLs require prompt download.

Authentication

Benchmark workers use server-side IDEOGRAM_API_KEY through Api-Key to https://api.ideogram.ai. Metrics label endpoint, status, stage, and content-free workload class, never prompt or image content.

Instructions

1. Measure queue, upload, generation, reconciliation, download, validation, and storage latency separately at p50, p95, and p99.
2. Confirm the selected endpoint is the narrowest route that meets model, transparency, edit, or tool requirements.
3. Bound input bytes, dimensions, output count, and post-processing; reject work unlikely to meet its deadline.
4. Move long work to async, persist generation_id, acknowledge application requests early, and reconcile by webhook plus polling.
5. Tune shared concurrency below observed capacity while tracking 429, timeout, queue age, and cost per useful output.
6. Compare one change at a time against the quality and safety floor; canary before rollout.
7. Remove benchmark assets and restore the prior setting when any guardrail regresses.

Tool Discipline

Use Read, Glob, and Grep to inspect metrics, queues, adapters, and fixtures. Use Write and Edit for approved instrumentation or tuning changes. Do not launch a paid benchmark or alter production capacity merely because this skill was selected.

Approval Boundaries

Require owners for benchmark spend, traffic sampling, model or rendering changes, quality evaluation, concurrency increases, and deployment. Never trade away safety checks or durable persistence for lower apparent latency.

Error Handling

• Unsupported V4 FLASH is a validation defect, not a performance strategy.
• A faster response with an unsafe or unpersisted image is not a successful sample.
• Stop a benchmark on rising errors, queue runaway, budget exhaustion, or storage cleanup fa…

Ideogram Production Readiness Gate

Overview

Produce a fail-closed release decision for an Ideogram integration. A visually successful test is only one signal; production readiness also requires owned billing, secure credentials, bounded capacity, moderation, durable assets, async reconciliation, telemetry, and a tested rollback.

Prerequisites

• Immutable release SHA, target environment, change owner, approver, and deployment window.
• Current architecture, endpoint inventory, tests, SLOs, budgets, retention, and incident runbook.
• Staging parity and a synthetic canary that contains no customer-derived content.

Current Contract

Live API calls require accepted terms, payment method, positive prepaid credit, and a valid Api-Key. Generation routes differ by endpoint and sync or async lifecycle. Safety is item-level, image URLs expire, and default capacity is documented as 10 in-flight requests.

Authentication

Confirm a target-environment secret reference, server-only injection, correct Api-Key header, scoped application authorization, and exercised revocation. Never place a real key in the release artifact or checklist evidence.

Instructions

1. Freeze the SHA and compare implemented endpoints, multipart fields, and schemas to current first-party docs.
2. Verify terms, positive credit, billing owner, alert thresholds, and a response to exhausted balance.
3. Prove secret handling, tenant authorization, media validation, safety and copyright policy, and retention controls.
4. Test sync and async success, unsafe output, every handled error class, webhook verification, polling fallback, duplicates, and terminal-state closure.
5. Confirm account-level concurrency, queue bounds, deadlines, storage download, expiring-URL removal, and object deletion.
6. Review dashboards, alerts, on-call ownership, support escalation, and content-free evidence.
7. Run a staging canary, execute rollback rehearsal, obtain explicit approval, then deploy a bounded production canary.
8. Reconcile final state and stop or roll back on any failed gate.

Tool Discipline

Use Read, Glob, and Grep to inspect release evidence. Use Write and Edit only for approved fixes or release documentation. Do not deploy, add credit, rotate keys, alter policy, or run production generation by invocation alone.

Approval Boundaries

The named approver owns live spend, production traffic, policy settings, and rollback acceptance. Missing evidence, unknown asset retention, unverified webhook signatures, or an untested rollback yields a no-go decision.

Error Handling

• Stop on schema drift, secret exposure, unsafe-publication paths, unbounded queueing, or inability to persist output.
• Never waive a failed gate because the canary image looks correct.
…

Ideogram Concurrency and Queue Control

Overview

Keep paid image work inside a measurable concurrency envelope. Combine admission control, tenant fairness, operation deadlines, and endpoint-aware retry so a traffic burst does not become duplicate spend, an unbounded queue, or persistent 429 pressure.

Prerequisites

• Request arrival rate, latency objective, output count, endpoint mix, and cost ceiling.
• Queue ownership, per-tenant policy, cancellation behavior, and overload response.
• Current account capacity and an approved contact path for increased scale.

Current Contract

Ideogram's API overview documents a default limit of 10 in-flight requests and directs larger-capacity needs to partnership@ideogram.ai. This is a concurrency boundary, not permission to launch ten workers per process. Account-wide observed behavior remains authoritative.

Authentication

Workers inject IDEOGRAM_API_KEY server-side and send Api-Key only to https://api.ideogram.ai. Queue records and metrics must exclude keys, prompts, images, and response URLs.

Instructions

1. Measure arrival rate, service time by endpoint, current in-flight count, queue age, timeout rate, and 429 responses.
2. Place a shared account-level semaphore below the verified limit; start conservatively and reserve capacity for recovery probes.
3. Add bounded per-tenant admission, queue length, age, output count, and total operation deadlines.
4. Prefer asynchronous endpoints for work that cannot fit an interactive deadline and persist each generation_id.
5. Retry only classified transient responses using server guidance when present, exponential backoff with jitter, and a strict attempt ceiling.
6. Prevent ambiguous duplicate generation by reconciling known async identifiers before resubmission.
7. Raise capacity only through the vendor path and a reviewed load plan; canary the new limit.

Tool Discipline

Use Read, Glob, and Grep for queue, worker, metric, and fixture inspection. Use Write and Edit for approved limit, test, or documentation changes. Invocation does not authorize load generation, quota negotiation, or increased production concurrency.

Approval Boundaries

Require owners for live load tests, spend, tenant-priority changes, queue dropping, capacity increases, and deployment. Document how queued work is cancelled or drained before changing the envelope.

Error Handling

• A 429 is an admission-control signal; immediate retries amplify pressure.
• Expired queue work should terminate before calling Ideogram, not after spending credit.
• Do not retry 400, 401, 422, unsafe output, or an already accepted async submission as i…

Ideogram Reference Architecture

Overview

Define ownership and data flow for a production Ideogram integration. Keep user authorization, paid vendor authority, request validation, async state, event verification, content review, durable media, and audit evidence as explicit components.

Prerequisites

• Workload, tenant and identity model, data class, SLO, budget, region, and retention policy.
• Expected endpoint mix, input sizes, concurrency, publication destinations, and failure modes.
• Owners for billing, security, moderation, storage, operations, and vendor escalation.

Current Contract

The API uses server-side Api-Key, endpoint-specific multipart requests, sync and async generation, item-level safety, signed async webhooks, polling, and temporary asset URLs. Default capacity is 10 in-flight requests. These contracts require stateful application orchestration even when the product experience is synchronous.

Authentication

Place IDEOGRAM_API_KEY only in a private vendor adapter. The policy gateway authenticates application identities and authorizes tenant, use case, spend, input, output, and destination separately.

Instructions

1. Define ingress and policy gateway boundaries for identity, tenant, rights, media validation, safety, copyright settings, budget, and admission.
2. Route accepted work to a durable queue and an account-level concurrency controller.
3. Use a vendor adapter that owns endpoint schemas, multipart, deadlines, typed errors, and content-free telemetry.
4. Persist request and generation_id state before async delivery, then reconcile verified webhooks with polling.
5. Pass safe outputs through a downloader that validates media and stores opaque tenant-scoped objects immediately.
6. Publish only from the application object store after required review; never authorize from a vendor URL.
7. Add outbox, audit, deletion, incident, canary, and rollback paths with explicit owners.

Tool Discipline

Use Read, Glob, and Grep to ground the design in the actual repository and infrastructure. Use Write and Edit for approved architecture records or implementation. Do not provision services, create keys, or deploy from a design invocation.

Approval Boundaries

Require accountable review for trust-boundary changes, public ingress, data residency, sensitive media, external publication, retention, spend, and production topology. Record unresolved assumptions as blockers.

Error Handling

• Keep queue acceptance distinct from vendor acceptance and durable asset completion.
• Reconcile duplicate or missing events without duplicate paid submissions.
• Quarantine unsafe, malformed, oversized, or tenant-mismatched media before publication.

Output

Return components, flows, …

Ideogram REST Adapter Patterns

Overview

Contain Ideogram transport behavior behind a small application-owned interface. Preserve endpoint-specific multipart contracts, error bodies, safety outcomes, asynchronous identifiers, and storage handoff without coupling business logic to raw vendor payloads.

Prerequisites

• A target language, HTTP client, schema library, test runner, and adapter ownership boundary.
• Current OpenAPI plus endpoint documentation for the exact route.
• Defined deadlines, concurrency, retry, data handling, and compatibility policies.

Current Contract

Ideogram exposes REST and an OpenAPI document. Endpoint payloads are not interchangeable: V4 generation uses multipart form fields, some operations include files, and asynchronous routes return a generation identifier for later reconciliation. Avoid presenting a third-party package or local wrapper as an official Ideogram SDK.

Authentication

Inject IDEOGRAM_API_KEY only inside the trusted transport adapter and send it as Api-Key to https://api.ideogram.ai. Redact headers, multipart content, prompts, image inputs, response URLs, and binary bodies from logs and exceptions.

Instructions

1. Inventory only the endpoint families required by the application and pin their current schemas.
2. Define owned request types that make mutually exclusive fields such as text_prompt and json_prompt impossible to combine.
3. Centralize host, authentication, deadlines, response byte limits, error decoding, and content-type checks.
4. Preserve vendor status, request or generation identifiers, is_image_safe, and unknown fields needed for drift review.
5. Separate submission, polling, webhook reconciliation, asset download, and durable storage interfaces.
6. Retry only classified transient failures with bounded jitter and an operation deadline; never replay ambiguous writes blindly.
7. Validate with synthetic fixtures and one approved live smoke after schema or endpoint changes.

Tool Discipline

Use Read, Glob, and Grep to identify existing clients and call sites. Use Write and Edit only for approved adapter, type, test, or documentation changes. Selection does not authorize package installation, live spend, or replacement of a production client.

Approval Boundaries

Require review before adding dependencies, changing retry semantics, exposing new prompt or image fields, switching endpoints, enabling paid traffic, or altering durable storage. Keep vendor migration and application API compatibility decisions explicit.

Error Handling

• Return typed authentication, validation, throttling, capacity, unsafe-output, timeout, and unknown-vendor errors.
• Preserve enough sanitized response detail to diagnose …

Ideogram Security Boundary

Overview

Threat-model the full image lifecycle rather than only the API key. Protect server-side authority, uploaded bytes, prompt and structured-description content, safety decisions, copyright settings, temporary vendor URLs, durable assets, and cross-tenant access.

Prerequisites

• Data classification, tenant model, rights policy, moderation owner, and retention schedule.
• Architecture showing upload, API, queue, webhook, download, storage, and publishing boundaries.
• Incident paths for credential exposure, unsafe output, malicious media, and unauthorized asset access.

Current Contract

Ideogram uses a server-side Api-Key. Returned items expose is_image_safe; unsafe items can have an empty URL. V4 supports enable_copyright_detection, and request plus organization settings combine as an OR gate. Generated URLs expire and must not become the application's authorization layer.

Authentication

Store IDEOGRAM_API_KEY in a managed secret store and send it only to https://api.ideogram.ai. Authenticate application users separately, authorize each operation and object by tenant, and issue application-owned short-lived download access after durable storage.

Instructions

1. Map every trust boundary and classify keys, prompts, structured prompts, uploads, masks, generated assets, metadata, and logs.
2. Keep paid API calls behind a server-side policy enforcement point with tenant authentication, authorization, budgets, and rate controls.
3. Validate media signatures, types, dimensions, byte limits, decompression behavior, and malware policy before forwarding.
4. Apply rights, content-safety, and copyright-detection policy before generation and again before publication.
5. Check is_image_safe, validate download type and size, store under opaque tenant-scoped keys, and discard vendor URLs.
6. Encrypt retained objects, restrict service identities, log content-free decisions, and enforce deletion.
7. Test key rotation, unsafe output, cross-tenant denial, malicious upload, expired URL, and object deletion.

Tool Discipline

Use Read, Glob, and Grep to inspect code, policies, infrastructure, and fixtures. Use Write and Edit for approved hardening and tests. Do not open customer media, rotate production keys, weaken policy, or run live generation without authority.

Approval Boundaries

Require accountable approval for sensitive-image processing, copyright-control changes, external publication, retention exceptions, identity or role changes, key rotation, and production rollout. Fail closed when rights or tenant ownership is ambiguous.

Error Handling

• Revoke and rotate an exposed key; deleting a log line alone is insufficient.
• Treat uns…

Ideogram Contract Upgrade

Overview

Move a bounded adapter contract to a current Ideogram route without mixing the change with a broad product migration. Diff OpenAPI and endpoint documentation, update owned types and fixtures, run shadow comparisons, and preserve an explicit traffic rollback.

Prerequisites

• Current adapter SHA, endpoint inventory, target contract, consumers, and accountable owner.
• Captured sanitized fixtures and compatibility requirements.
• Canary budget, traffic control, storage parity, and rollback deadline.

Current Contract

The current surface spans V4, P-Image, V3, outcome-focused tools, custom training, and routes labeled Legacy Endpoints. V4 generation uses endpoint-specific multipart forms; text_prompt and json_prompt are mutually exclusive, and current V4 FLASH support must not be inferred from V3 examples.

Authentication

Keep the same server-side Api-Key boundary unless a documented first-party auth change is part of the reviewed diff. Never copy production credentials or payloads into migration fixtures.

Instructions

1. Inventory current routes, methods, fields, enums, errors, async states, safety fields, and downstream storage assumptions.
2. Retrieve current OpenAPI and endpoint docs, then classify additive, changed, deprecated, legacy, and undocumented differences.
3. Update owned types and route adapters while preserving unknown fields needed for drift detection.
4. Build sanitized before-and-after fixtures for success, unsafe output, validation, throttling, capacity, webhook, polling, and URL expiry.
5. Run offline contract tests and a staging shadow that does not double-publish or overwrite assets.
6. Canary a bounded live slice within an approved credit ceiling and compare status, latency, safety, output count, and storage outcomes.
7. Promote only after convergence; retain the prior route and state reconciliation until the rollback window closes.

Tool Discipline

Use Read, Glob, and Grep for routes, schemas, consumers, and fixtures. Use Write and Edit for approved adapter, test, and migration documentation changes. Do not change live traffic or run parallel paid generation without approval.

Approval Boundaries

Require owners for endpoint choice, compatibility exceptions, model or rendering changes, extra spend, safety differences, and production cutover. Removing a legacy route requires proof that no consumer or in-flight generation depends on it.

Error Handling

• Stop when the target schema is undocumented or response safety fields cannot be reconciled.
• Do not coerce a V3 enum into V4 merely because names look similar.
• On canary divergence, halt target traffic, preserve identifiers, and reconcile stored assets before rollbac…

Ideogram Webhook Verification and Reconciliation

Overview

Accept Ideogram asynchronous completion only after cryptographic verification and idempotent reconciliation. Use the raw request body, bind all signed headers, acknowledge quickly, and retain polling as a recovery path because delivery is not guaranteed.

Prerequisites

• A public HTTPS receiver, raw-body access, durable event store, queue, and clock.
• The submitted generation_id, destination object policy, and polling reconciler.
• Local Ed25519 fixtures for valid, invalid, stale, duplicate, and rotated-key deliveries.

Current Contract

Async requests can include a webhook URL and return generation_id. Ideogram signs callbacks with Ed25519 and publishes keys at https://api.ideogram.ai/v1/.well-known/jwks.json. Signed headers identify generation, user, timestamp, key, and signature. Deliveries may duplicate, retries are limited, and polling remains necessary.

Authentication

Webhook trust comes from signature verification, not a shared API key in the callback. Normal polling uses server-side IDEOGRAM_API_KEY in the Api-Key header; never expose it to the receiver request.

Instructions

1. Capture the raw body bytes and required generation-ID, user-ID, timestamp, key-ID, and signature headers before JSON parsing.
2. Compute SHA-256 over the raw body and construct the signed message as generation ID, newline, user ID, newline, timestamp, newline, then the lowercase body hash.
3. Resolve the key ID from the JWKS cache and verify the lowercase-hex Ed25519 signature.
4. Enforce a bounded timestamp window and bind the callback to a known submitted generation and expected application tenant.
5. Persist a deduplication record keyed by generation and delivery evidence, return 2xx quickly, and enqueue processing.
6. Validate safety, download approved output, persist it, and transition state idempotently.
7. On verification failure, refresh JWKS once; on missing delivery, append the returned generation ID to GET /v1/generations/ and poll that resource.

Tool Discipline

Use Read, Glob, and Grep for receiver, queue, state, and fixtures. Use Write and Edit for approved implementation and tests. Do not expose a receiver, submit paid async work, or replay production events by invocation alone.

Approval Boundaries

Require approval for public routing, production keys, live submissions, replay-window changes, retained identifiers, and storage or publishing. Reject callbacks that cannot be tied to an authorized application operation.

Error Handling

• Never verify reserialized JSON; whitespace changes break raw-body integrity.
• Refetch JWKS once on an unknown key or verification failure, then reject.
…