Ideogram Reference Architecture
Overview
Production architecture for AI image generation with Ideogram at scale. Covers prompt templating for brand consistency, generation pipelines using all six API endpoints, asset storage and CDN delivery, and metadata tracking for reproducibility.
Architecture Diagram
┌─────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────┘
Instructions
Step 1: Prompt Template System
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;
}
Step 2: Generation Service
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",
},
}),
});
(!response.) ();
result = response.();
image = result.[];
imgResp = (image.);
buffer = .( imgResp.());
(outputDir, { : });
filename = ;
((outputDir, filename), buffer);
{
: (outputDir, filename),
: image.,
prompt,
: image.,
: templateKey,
};
}
Step 3: Multi-Format Asset Pipeline
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);
await sharp(asset.localPath)
.webp({ quality: 85 })
.toFile(asset.localPath.replace(".png", ".webp"));
await new Promise(r => setTimeout(r, 3000));
}
const manifest = results.map(r => ({
template: r.template,
seed: r.seed,
: r.,
: {
: r.,
: r..(, ),
},
}));
(, .(manifest, , ));
.();
results;
}
Step 4: Describe-then-Remix Pipeline
async function referenceBasedGeneration(referenceImagePath: string, modifications: string) {
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;
const form2 = new FormData();
form2.append("image", new Blob([readFileSync(referenceImagePath)]));
form2.append(, );
form2.(, );
form2.(, );
remixResp = (, {
: ,
: { : },
: form2,
});
remixResp.();
}
Project Structure
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)
Error Handling
| Issue | Cause | Solution |
|---|
| Inconsistent style | No template system | Use branded prompt templates |
| URL expired | Late download | Download in same function call |
| Text misspelled | Prompt too vague | Use DESIGN style, quote exact text |
| Wrong aspect ratio | Template mismatch | Map templates to target platforms |
Output
- Prompt template system for brand consistency
- Generation service with auto-download
- Multi-format asset pipeline (PNG + WebP)
- Describe-then-remix pipeline for reference-based generation
- Asset manifest for tracking and reproducibility
Resources
Next Steps
For multi-environment setup, see ideogram-multi-env-setup.
