Ideogram Sdk PatternsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ideogram-sdk-patterns
description: >-
  Design an owned Ideogram REST adapter for multipart uploads, typed responses, deadlines, and vendor isolation. Use when building or reviewing application client code without inventing an official SDK. Trigger with "wrap Ideogram API", "build an Ideogram client", or "review Ideogram adapter code".
allowed-tools: Read,Glob,Grep,Write,Edit
argument-hint: "<language> <adapter-path> <endpoint-family>"
version: 1.11.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags: [saas, ideogram, architecture]
model: inherit
effort: high
compatibility: "Designed for Claude Code; examples are transport patterns, not claims of an official SDK"
---
# 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 `400` and `422` without copying sensitive content.
- Fail closed on unexpected content type, oversized download, unsafe output, or unrecognized terminal state.

## Output

Return the adapter surface, endpoint map, schema version or retrieval date, retry and deadline policy, tests run, compatibility risks, live-check status, and rollback plan. Do not return credentials, prompts, image bytes, or expiring URLs.

## Examples

- Expose `generateV4`, `submitV4`, `getGeneration`, and `persistAsset` as separate owned operations.
- Adapt a vendor `429` into an application `CapacityDeferred` result carrying sanitized retry metadata.

## Validation

Run contract and call-site tests, compare multipart field names to first-party docs, inject every error class, and verify logs remain content-free. Confirm the old adapter can be restored without losing in-flight generation state.

## Resources

- [Current first-party evidence map](references/official-docs.md) — 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.

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.