Ideogram

Purpose

Generate images with Ideogram's v3 API: the strongest option in the catalog for text-in-image rendering (thumbnails and carousels with real words), plus Magic Fill editing and style remix, with upscaling and image description on the same key. Use when Michael needs images that contain legible text.

Tooling

All commands go through bin/ideogram.py (multipart form posts):

bin/ideogram.py auth                                                      # verify the API key (free balance read)
bin/ideogram.py balance                                                   # read billing balance (free)
bin/ideogram.py generate --prompt "retro poster that says SUMMER" --json '{"aspect_ratio": "16x9"}'
bin/ideogram.py edit --prompt "replace the sign with OPEN" --image ./sign.png     # Magic Fill edit
bin/ideogram.py remix --prompt "same scene, watercolor style" --image ./scene.png # style transfer
bin/ideogram.py upscale --image ./small.png                               # upscale
bin/ideogram.py describe --image ./photo.png                              # describe an image

generate returns image URLs in the response. Ideogram is SYNCHRONOUS (no job polling), which makes it the simplest image integration in the catalog.

Auth

• Provider id: ideogram (credential is collected as custom.ideogram)
• Collection: API key via the secure credential flow (credentials.request_api_access); created in the Ideogram developer dashboard
• Allowed hosts: api.ideogram.ai
• Status check: bin/ideogram.py auth (must return "ok": true). The key is sent as the Api-Key header. HEADER NOTE: the research dossier documented "header auth" without naming the header; Api-Key is per Ideogram's published API docs. Verify against developer.ideogram.ai on first live use and correct bin/ideogram.py if it differs.

Operating Rules

1. Every generation/edit/remix/upscale spends balance (~$0.05-0.08/image by model/speed tier). Confirm with Michael before each one.
2. COST WARNING: Ideogram billing auto-tops-up: it refills to $20 when the balance drops below $10 (configurable). Read balance first so top-ups never surprise anyone.
3. Image URLs expire. Download immediately after generation; never store the URL as the artifact.
4. Default rate limit is 10 in-flight requests. Do not fan out more than that.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/ideogram.py). Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/ideogram.py

Maturity

🧪 Draft: written from Ideogram's published OpenAPI 3.1 spec via the research dossier; not yet live-tested end-to-end. The Api-Key header name and the /api/v1/billing path need a live check on first use.