Ideogram Reference Architecture

┌─────────────────────────────────────────────────────────┐
│  Prompt Engineering Layer                                │
│  Templates │ Brand Guidelines │ Negative Prompts         │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Ideogram API (api.ideogram.ai)                          │
│  ┌──────────┐ ┌────────┐ ┌───────┐ ┌────────┐          │
│  │ Generate │ │ Edit   │ │ Remix │ │Describe│          │
│  │(text→img)│ │(inpaint)│ │(vary) │ │(img→txt)│         │
│  └────┬─────┘ └───┬────┘ └──┬────┘ └───┬────┘          │
│       │           │         │          │                │
│  ┌────┴───────────┴─────────┴──────────┘                │
│  │  ┌──────────┐  ┌─────────┐                           │
│  │  │ Upscale  │  │ Reframe │                           │
│  │  └────┬─────┘  └────┬────┘                           │
│  └───────┴──────────────┘                               │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Post-Processing & Storage                               │
│  Download │ Resize │ WebP Convert │ S3/GCS │ CDN        │
└─────────────────────────────────────────────────────────┘

interface PromptTemplate {
  name: string;
  base: string;
  style: string;
  negativePrompt: string;
  aspectRatio: string;
  model: string;
  renderingSpeed?: string;
}

const BRAND_TEMPLATES: Record<string, PromptTemplate> = {
  socialPost: {
    name: "Social Media Post",
    base: "{subject}, modern clean design, vibrant colors, professional",
    style: "DESIGN",
    negativePrompt: "blurry text, misspelled, watermark, low quality",
    aspectRatio: "ASPECT_1_1",
    model: "V_2",
  },
  blogHero: {
    name: "Blog Hero Image",
    base: "{subject}, editorial photography, wide composition, cinematic lighting",
    style: "REALISTIC",
    negativePrompt: "text overlay, watermark, blurry, oversaturated",
    aspectRatio: "ASPECT_16_9",
    model: "V_2",
  },
  storyVertical: {
    name: "Story / Reel",
    base: "{subject}, vertical composition, eye-catching, bold colors",
    style: "DESIGN",
    negativePrompt: "horizontal layout, small text, blurry",
    aspectRatio: "ASPECT_9_16",
    model: "V_2_TURBO",
  },
  ogImage: {
    name: "Open Graph Image",
    base: '{subject}, with text "{title}" in bold clean font, tech aesthetic',
    style: "DESIGN",
    negativePrompt: "blurry text, misspelled words, cluttered",
    aspectRatio: "ASPECT_16_9",
    model: "V_2",
  },
};

function buildPrompt(templateKey: string, vars: Record<string, string>): string {
  const template = BRAND_TEMPLATES[templateKey];
  if (!template) throw new Error(`Unknown template: ${templateKey}`);
  let prompt = template.base;
  for (const [key, value] of Object.entries(vars)) {
    prompt = prompt.replace(`{${key}}`, value);
  }
  return prompt;
}

import { writeFileSync, mkdirSync } from "fs";
import { join } from "path";

const API_KEY = process.env.IDEOGRAM_API_KEY!;

async function generateFromTemplate(
  templateKey: string,
  vars: Record<string, string>,
  outputDir = "./assets"
) {
  const template = BRAND_TEMPLATES[templateKey];
  const prompt = buildPrompt(templateKey, vars);

  const response = await fetch("https://api.ideogram.ai/generate", {
    method: "POST",
    headers: { "Api-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      image_request: {
        prompt,
        model: template.model,
        style_type: template.style,
        aspect_ratio: template.aspectRatio,
        negative_prompt: template.negativePrompt,
        magic_prompt_option: "AUTO",
      },
    }),
  });

  if (!response.ok) throw new Error(`Generate failed: ${response.status}`);
  const result = await response.json();
  const image = result.data[0];

  // Download immediately (URLs expire ~1hr)
  const imgResp = await fetch(image.url);
  const buffer = Buffer.from(await imgResp.arrayBuffer());
  mkdirSync(outputDir, { recursive: true });
  const filename = `${templateKey}-${image.seed}.png`;
  writeFileSync(join(outputDir, filename), buffer);

  return {
    localPath: join(outputDir, filename),
    seed: image.seed,
    prompt,
    resolution: image.resolution,
    template: templateKey,
  };
}

import sharp from "sharp";

async function generateBrandAssetSet(subject: string, title: string) {
  const results = [];

  for (const [key, template] of Object.entries(BRAND_TEMPLATES)) {
    const asset = await generateFromTemplate(key, { subject, title });
    results.push(asset);

    // Generate WebP variant for web
    await sharp(asset.localPath)
      .webp({ quality: 85 })
      .toFile(asset.localPath.replace(".png", ".webp"));

    // Rate limit courtesy
    await new Promise(r => setTimeout(r, 3000));
  }

  // Generate manifest for asset tracking
  const manifest = results.map(r => ({
    template: r.template,
    seed: r.seed,
    prompt: r.prompt,
    files: {
      png: r.localPath,
      webp: r.localPath.replace(".png", ".webp"),
    },
  }));

  writeFileSync("./assets/manifest.json", JSON.stringify(manifest, null, 2));
  console.log(`Generated ${results.length} brand assets with manifest`);
  return results;
}

// Use Describe to analyze a reference image, then Remix to create variations
async function referenceBasedGeneration(referenceImagePath: string, modifications: string) {
  // Step 1: Describe the reference image
  const form1 = new FormData();
  form1.append("image_file", new Blob([readFileSync(referenceImagePath)]));
  form1.append("describe_model_version", "V_3");

  const descResp = await fetch("https://api.ideogram.ai/describe", {
    method: "POST",
    headers: { "Api-Key": API_KEY },
    body: form1,
  });
  const descriptions = await descResp.json();
  const basePrompt = descriptions.descriptions[0].text;

  // Step 2: Remix with modifications
  const form2 = new FormData();
  form2.append("image", new Blob([readFileSync(referenceImagePath)]));
  form2.append("prompt", `${basePrompt}, ${modifications}`);
  form2.append("image_weight", "40");
  form2.append("rendering_speed", "DEFAULT");

  const remixResp = await fetch("https://api.ideogram.ai/v1/ideogram-v3/remix", {
    method: "POST",
    headers: { "Api-Key": API_KEY },
    body: form2,
  });

  return remixResp.json();
}

project/
├── src/
│   ├── ideogram/
│   │   ├── client.ts          # API wrapper
│   │   ├── templates.ts       # Prompt templates
│   │   ├── pipeline.ts        # Generation pipeline
│   │   └── types.ts           # TypeScript types
│   ├── storage/
│   │   └── s3.ts              # Image upload to S3/GCS
│   └── api/
│       └── generate.ts        # API route handler
├── assets/                    # Generated image output
│   └── manifest.json          # Asset tracking
├── tests/
│   ├── templates.test.ts      # Prompt template tests
│   └── pipeline.test.ts       # Pipeline tests (mocked)
└── config/
    ├── ideogram.ts            # API configuration
    └── templates.json         # Prompt templates (optional)