ideogram-deploy-integration

Ideogram Deploy Integration

Overview

Deploy Ideogram image generation endpoints to Vercel, Cloud Run, or Docker. Key concerns: API key security, function timeouts (generation takes 5-15s), image persistence (URLs expire), and CDN integration for serving generated images.

Prerequisites

• IDEOGRAM_API_KEY configured
• Cloud storage for generated images (S3, GCS, or R2)
• Platform CLI installed (vercel, gcloud, or docker)

Instructions

Step 1: API Endpoint (Next.js / Vercel)

// app/api/generate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: process.env.AWS_REGION });

export async function POST(req: NextRequest) {
  const { prompt, style, aspectRatio } = await req.json();

  if (!prompt || prompt.length > 10000) {
    return NextResponse.json({ error: "Invalid prompt" }, { status: 400 });
  }

  // Generate image via Ideogram
  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,
        model: "V_2",
        style_type: style || "AUTO",
        aspect_ratio: aspectRatio || "ASPECT_1_1",
        magic_prompt_option: "AUTO",
      },
    }),
  });

  if (!response.ok) {
    const err = await response.text();
    return NextResponse.json({ error: `Generation failed: ${response.status}` }, { status: 502 });
  }

  const result = await response.json();
  const image = result.data[0];

  // Download and persist to S3 (Ideogram URLs expire)
  const imgResponse = await fetch(image.url);
  const buffer = Buffer.from(await imgResponse.arrayBuffer());
  const key = `generated/${image.seed}-${Date.now()}.png`;

  await s3.send(new PutObjectCommand({
    Bucket: process.env.S3_BUCKET!,
    Key: key,
    Body: buffer,
    ContentType: "image/png",
  }));

  return NextResponse.json({
    url: `https://${process.env.CDN_DOMAIN}/${key}`,
    seed: image.seed,
    resolution: image.resolution,
    style: image.style_type,
  });
}

export const maxDuration = 60; // Vercel function timeout

Step 2: Vercel Configuration

{
  "functions": {
    "app/api/generate/route.ts": {
      "maxDuration": 60
    }
  },
  "env": {
    "IDEOGRAM_API_KEY": "@ideogram-api-key"
  }
}

set -euo pipefail
# Set secrets
vercel env add IDEOGRAM_API_KEY production
vercel env add S3_BUCKET production
vercel env add CDN_DOMAIN production

Step 3: Cloud Run Deployment

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
# Cloud Run sets PORT automatically
CMD ["node", "dist/server.js"]

set -euo pipefail
# Store API key in Secret Manager
echo -n "$IDEOGRAM_API_KEY" | gcloud secrets create ideogram-api-key --data-file=-

# Deploy with secret mount
gcloud run deploy ideogram-service \
  --image=gcr.io/$PROJECT_ID/ideogram-service \
  --set-secrets=IDEOGRAM_API_KEY=ideogram-api-key:latest \
  --timeout=120 \
  --memory=512Mi \
  --max-instances=10 \
  --allow-unauthenticated

Step 4: Docker Compose (Self-Hosted)

# docker-compose.yml
services:
  ideogram-api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - IDEOGRAM_API_KEY=${IDEOGRAM_API_KEY}
      - S3_BUCKET=${S3_BUCKET}
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Step 5: Health Check Endpoint

// app/api/health/route.ts
export async function GET() {
  const checks = {
    ideogram: {
      configured: !!process.env.IDEOGRAM_API_KEY,
      keyLength: process.env.IDEOGRAM_API_KEY?.length ?? 0,
    },
    storage: {
      configured: !!process.env.S3_BUCKET,
    },
  };

  const healthy = checks.ideogram.configured && checks.storage.configured;

  return Response.json({
    status: healthy ? "healthy" : "degraded",
    checks,
  }, { status: healthy ? 200 : 503 });
}

Error Handling

Issue	Cause	Solution
Function timeout	Generation takes 5-15s	Set timeout to 60s+
Content filtered	Prompt policy violation	Return 422 with user-friendly message
Storage upload fails	Bad credentials	Verify S3/GCS permissions
Rate limited	Too many concurrent users	Queue generation jobs with BullMQ
Expired URL	Late download	Download immediately in same request

Output

• Deployed API endpoint with image generation
• Images persisted to durable storage with CDN URLs
• Health check endpoint for monitoring
• Platform-specific configuration files

Resources

• Ideogram API Reference
• Vercel Functions
• Cloud Run Docs

Next Steps

For event-driven patterns, see ideogram-webhooks-events.