ideogram-prod-checklist

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

• Ideogram API Overview
• API Setup

Next Steps

For version upgrades, see ideogram-upgrade-migration.