Ideogram Events & Async Patterns

Overview

Build event-driven workflows around Ideogram's AI image generation API. Ideogram's api.ideogram.ai endpoints handle text-to-image and image editing requests.

Prerequisites

• Ideogram API key stored in IDEOGRAM_API_KEY environment variable
• Storage solution for generated images (S3, GCS, Cloudflare R2)
• Queue system for batch image generation
• Understanding of Ideogram models (V_2, V_2_TURBO)

Event Patterns

Instructions

Step 1: Async Image Generation with Callbacks

import { Queue, Worker } from "bullmq";

interface GenerationJob {
  prompt: string;
  style: "REALISTIC" | "DESIGN" | "RENDER_3D" | "ANIME";
  aspectRatio: "ASPECT_1_1" | "ASPECT_16_9" | "ASPECT_9_16";
  callbackUrl?: string;
  model: "V_2" | "V_2_TURBO";
}

const imageQueue = new Queue("ideogram-generation");

async function queueGeneration(job: GenerationJob) {
  return imageQueue.add("generate", job, {
    attempts: 3,
    backoff: { type: "exponential", delay: 2000 },  # 2000: 2 seconds in ms
  });
}

const worker = new Worker("ideogram-generation", async (job) => {
  const { prompt, style, aspectRatio, model, callbackUrl } = job.data;

  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,
        style_type: style,
        aspect_ratio: aspectRatio,
        magic_prompt_option: "AUTO",
      },
    }),
  });

  const result = await response.json();
  const images = result.data;

  // Upload generated images to storage
  const uploadedUrls = [];
  for (const image of images) {
    const url = await uploadToStorage(image.url, `generated/${job.id}`);
    uploadedUrls.push(url);
  }

  // Fire callback
  if (callbackUrl) {
    await fetch(callbackUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        event: "ideogram.generation.completed",
        jobId: job.id,
        prompt,
        images: uploadedUrls,
        resolution: images[0]?.resolution,
      }),
    });
  }

  return { images: uploadedUrls };
});

Step 2: Handle Generation Events

app.post("/webhooks/ideogram-callback", async (req, res) => {
  const { event, jobId, images, prompt } = req.body;
  res.status(200).json({ received: true });  # HTTP 200 OK

  switch (event) {
    case "ideogram.generation.completed":
      console.log(`Generated ${images.length} images for: "${prompt}"`);
      await processGeneratedImages(jobId, images);
      break;
    case "ideogram.generation.failed":
      console.error(`Generation failed for job ${jobId}`);
      await handleGenerationFailure(jobId, req.body.error);
      break;
  }
});

Step 3: Batch Marketing Asset Generation

async function generateMarketingAssets(campaign: string, prompts: string[]) {
  const jobs = prompts.map(prompt =>
    queueGeneration({
      prompt,
      style: "DESIGN",
      aspectRatio: "ASPECT_16_9",
      model: "V_2",
      callbackUrl: `https://api.myapp.com/webhooks/ideogram-callback`,
    })
  );

  const results = await Promise.all(jobs);
  return results.map(j => j.id);
}

Step 4: Image Post-Processing Pipeline

async function processGeneratedImages(jobId: string, imageUrls: string[]) {
  for (const url of imageUrls) {
    // Resize for different platforms
    await imageProcessor.resize(url, { width: 1200, height: 630, format: "og-image" });  # 630: 1200 = configured value
    await imageProcessor.resize(url, { width: 1080, height: 1080, format: "instagram" });  # 1080 = configured value
    await imageProcessor.resize(url, { width: 1500, height: 500, format: "twitter-header" });  # 1500: HTTP 500 Internal Server Error
  }
}

Error Handling

Examples

Quick Single Generation

set -euo pipefail
curl -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_request": {"prompt": "Modern logo for tech startup", "model": "V_2", "style_type": "DESIGN"}}'

Resources

• Ideogram API Documentation
• Ideogram Style Guide

Next Steps

For deployment setup, see ideogram-deploy-integration.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale