Ideogram Production Checklist Skill

Ideogram Production Checklist

Overview

Complete pre-flight checklist for deploying Ideogram image generation to production. Covers API key management, timeout configuration, image persistence, error handling, monitoring, and rollback procedures.

Prerequisites

Staging environment tested
Production API key created (separate from dev)
Image storage configured (S3, GCS, or R2)
Monitoring stack ready

Pre-Deployment Checklist

API Configuration

[ ] Production API key stored in secret manager (not .env file)
[ ] Key is separate from dev/staging keys
[ ] Auto top-up billing configured with appropriate limits
[ ] Base URL is https://api.ideogram.ai (no trailing slash)

Request Handling

[ ] Api-Key header used (not Authorization: Bearer)
[ ] Request timeout set to 60s+ (generation takes 5-15s, complex prompts longer)
[ ] Retry logic with exponential backoff on 429 and 5xx
[ ] Concurrency limited to 8 (below the 10 in-flight limit)
[ ] Prompt length validated (max 10,000 chars)

Image Persistence

[ ] Images downloaded immediately after generation (URLs expire ~1 hour)
[ ] Downloaded to durable storage (S3/GCS/R2), not local filesystem
[ ] Filenames include seed for reproducibility tracking
[ ] Generation metadata (prompt, seed, model, style) stored in database

Error Handling

[ ] 401 triggers key rotation alert
[ ] 422 (safety filter) logged with sanitized prompt for review
[ ] 429 handled with retry, not user-facing error
[ ] 402 (no credits) triggers billing alert and graceful degradation
[ ] Circuit breaker prevents cascading failures

Content Safety

[ ] Prompt sanitization removes PII before API call
[ ] User-submitted prompts validated server-side
[ ] is_image_safe response field checked before displaying to users
[ ] Content moderation layer for user-facing applications

Production Health Check

async function ideogramHealthCheck(): Promise<{
  status: "healthy" | "degraded" | "down";
  latencyMs: number;
  details: string;
}> {
  const start = Date.now();
  try {
    const response = await fetch("https://api.ideogram.ai/generate", {
      method: "POST",
      headers: {
        "Api-Key": process.env.IDEOGRAM_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        image_request: {
          prompt: "health check: simple blue dot",
          model: "V_2_TURBO",
          magic_prompt_option: "OFF",
        },
      }),
      signal: AbortSignal.timeout(30000),
    });

    const latencyMs = Date.now() - start;

    if (response.ok) {
      return { status: "healthy", latencyMs, details: "Generation succeeded" };
    }
    if (response.status === 429) {
      return { status: "degraded", latencyMs, details: "Rate limited" };
    }
    return { status: "down", latencyMs, details: `HTTP ${response.status}` };
  } catch (err: any) {
    return { status: "down", latencyMs: Date.now() - start, details: err.message };
  }
}

Deployment Script

set -euo pipefail
echo "=== Ideogram Pre-Flight Checks ==="

# 1. Verify production key
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request":{"prompt":"deploy check","model":"V_2_TURBO","magic_prompt_option":"OFF"}}')

if [ "$STATUS" != "200" ]; then
  echo "FAIL: API returned $STATUS"
  exit 1
fi
echo "PASS: API key valid (HTTP $STATUS)"

# 2. Verify image download
IMAGE_URL=$(curl -s -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request":{"prompt":"deploy check","model":"V_2_TURBO","magic_prompt_option":"OFF"}}' \
  | jq -r '.data[0].url')

DL_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$IMAGE_URL")
echo "PASS: Image download works (HTTP $DL_STATUS)"

echo "=== All pre-flight checks passed ==="

Alerting Rules

| Alert | Condition | Severity | |-------|-----------|----------| | API Unreachable | Health check returns down | P1 | | Auth Failure | Any 401 response | P1 | | Rate Limited | >5 consecutive 429 responses | P2 | | Slow Generation | P95 latency > 30 seconds | P2 | | Credits Low | Balance below $10 | P2 | | Safety Rejections | >10% of prompts rejected | P3 |

Rollback Procedure

set -euo pipefail
# If Ideogram is down or producing bad results
# 1. Enable fallback mode (disable image generation, show placeholders)
kubectl set env deployment/app IDEOGRAM_ENABLED=false
kubectl rollout restart deployment/app

# 2. Verify fallback is active
curl -s https://app.example.com/health | jq '.services.ideogram'

# 3. Re-enable when resolved
kubectl set env deployment/app IDEOGRAM_ENABLED=true
kubectl rollout restart deployment/app

Error Handling

| Alert | Condition | Action | |-------|-----------|--------| | API Down | 5xx or timeout | Enable fallback, notify on-call | | Key Revoked | 401 | Rotate key, update secrets | | Credits Empty | 402 | Top up billing, pause batch jobs | | Rate Flood | 429 sustained | Reduce concurrency, queue jobs |

Output

All checklist items verified
Health check endpoint configured
Alerting rules deployed
Rollback procedure tested

Resources

Next Steps

For version upgrades, see ideogram-upgrade-migration.

Agent Skills: Ideogram Production Checklist

Install this agent skill to your local

Skill Files