Ideogram Hello World

Overview

Generate your first AI image with Ideogram. Demonstrates the legacy /generate endpoint (JSON body) and the V3 /v1/ideogram-v3/generate endpoint (multipart form). Both return temporary image URLs that must be downloaded promptly.

Prerequisites

Completed ideogram-install-auth setup
IDEOGRAM_API_KEY environment variable set
Node.js 18+ or Python 3.10+

Instructions

Step 1: Quick Test with curl

set -euo pipefail
# Legacy endpoint (V_2 model, JSON body)
curl -s -X POST https://api.ideogram.ai/generate \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_request": {
      "prompt": "A cheerful golden retriever wearing sunglasses on a beach, with text saying \"Hello Ideogram!\"",
      "model": "V_2",
      "style_type": "REALISTIC",
      "aspect_ratio": "ASPECT_16_9",
      "magic_prompt_option": "AUTO"
    }
  }' | jq '.data[0] | {url, seed, resolution, is_image_safe}'

Step 2: TypeScript -- Generate and Download

// hello-ideogram.ts
import { writeFileSync } from "fs";

async function helloIdeogram() {
  // Generate an image with embedded text (Ideogram's specialty)
  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: 'Modern poster design with bold text "HELLO WORLD" in neon gradient, dark background, clean typography',
        model: "V_2",
        style_type: "DESIGN",
        aspect_ratio: "ASPECT_1_1",
        magic_prompt_option: "AUTO",
        num_images: 1,
      },
    }),
  });

  if (!response.ok) {
    throw new Error(`Generation failed: ${response.status} ${await response.text()}`);
  }

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

  console.log("Generated image:");
  console.log("  URL:", image.url);
  console.log("  Seed:", image.seed);
  console.log("  Resolution:", image.resolution);
  console.log("  Style:", image.style_type);
  console.log("  Safe:", image.is_image_safe);

  // Download immediately -- URLs expire after ~1 hour
  const imgResponse = await fetch(image.url);
  const buffer = Buffer.from(await imgResponse.arrayBuffer());
  writeFileSync("hello-ideogram.png", buffer);
  console.log("Saved to hello-ideogram.png");
}

helloIdeogram().catch(console.error);

Step 3: Python -- Generate and Download

# hello_ideogram.py
import os, requests

response = requests.post(
    "https://api.ideogram.ai/generate",
    headers={
        "Api-Key": os.environ["IDEOGRAM_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "image_request": {
            "prompt": 'Modern poster design with bold text "HELLO WORLD" in neon gradient, dark background',
            "model": "V_2",
            "style_type": "DESIGN",
            "aspect_ratio": "ASPECT_1_1",
            "magic_prompt_option": "AUTO",
        }
    },
)
response.raise_for_status()

image = response.json()["data"][0]
print(f"URL: {image['url']}")
print(f"Seed: {image['seed']}")

# Download the image (URLs expire)
img_data = requests.get(image["url"]).content
with open("hello-ideogram.png", "wb") as f:
    f.write(img_data)
print("Saved to hello-ideogram.png")

Key Parameters Quick Reference

Parameter	Values	Default
`model`	`V_1`, `V_1_TURBO`, `V_2`, `V_2_TURBO`, `V_2A`, `V_2A_TURBO`	`V_2`
`style_type`	`AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`, `RENDER_3D`, `ANIME`	`AUTO`
`aspect_ratio`	`ASPECT_1_1`, `ASPECT_16_9`, `ASPECT_9_16`, `ASPECT_3_2`, `ASPECT_2_3`, `ASPECT_4_3`, `ASPECT_3_4`, `ASPECT_10_16`, `ASPECT_16_10`, `ASPECT_1_3`, `ASPECT_3_1`	`ASPECT_1_1`
`magic_prompt_option`	`AUTO`, `ON`, `OFF`	`AUTO`
`num_images`	1-4	1

Response Shape

{
  "created": "2025-01-15T10:30:00Z",
  "data": [
    {
      "url": "https://ideogram.ai/assets/image/...",
      "prompt": "expanded prompt if magic_prompt was ON",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "style_type": "DESIGN"
    }
  ]
}

Error Handling

Error	HTTP Status	Cause	Solution
Auth error	401	Missing or invalid `Api-Key` header	Check `IDEOGRAM_API_KEY` env var
Safety rejected	422	Prompt failed content filter	Remove flagged terms, rephrase
Rate limited	429	Too many in-flight requests	Wait and retry with backoff
Bad request	400	Invalid parameter values	Check enum values match exactly

Output

Generated image file downloaded locally
Console output with URL, seed, resolution, and safety status
Seed value for reproducible regeneration

Resources

Next Steps

Proceed to ideogram-local-dev-loop for development workflow setup.

ideogram-hello-world