AI Image Generation

AI Image Generation

Generate images programmatically using OpenAI GPT Image, Google Gemini Imagen, or AWS Bedrock Titan Image Generator APIs. This skill covers API usage, prompt engineering, batch pipelines, and format handling.

Provider Comparison

When to choose which

• OpenAI: Best text rendering, native WebP, transparent backgrounds, streaming
• Gemini: Lower cost, good quality, simpler API surface
• Bedrock Titan: Use existing AWS credentials (no separate API key), cost-effective, good for teams already in AWS ecosystem. Supports image conditioning (Canny edge, segmentation).

Quick Start

For OpenAI and Gemini quick start code, see references/api-reference.md.

AWS Bedrock Titan — CLI

Requires AWS credentials (via gimme-aws-creds, SSO, or IAM role). Uses fileb:// for the body.

# Write the request body to a temp file
cat > /tmp/titan-request.json << 'EOF'
{
  "taskType": "TEXT_IMAGE",
  "textToImageParams": {
    "text": "A flowchart showing data flowing from API to database"
  },
  "imageGenerationConfig": {
    "quality": "standard",
    "numberOfImages": 1,
    "height": 1024,
    "width": 1024,
    "cfgScale": 8.0
  }
}
EOF

# Invoke the model (must use fileb:// not file://)
aws bedrock-runtime invoke-model \
  --region us-east-1 \
  --model-id amazon.titan-image-generator-v2:0 \
  --content-type application/json \
  --accept application/json \
  --body fileb:///tmp/titan-request.json \
  /tmp/titan-response.json

# Extract the base64 image and save as PNG
python3 -c "
import json, base64
with open('/tmp/titan-response.json') as f:
    data = json.load(f)
with open('output.png', 'wb') as f:
    f.write(base64.b64decode(data['images'][0]))
"

A helper script that wraps this entire flow is available at scripts/bedrock-generate.sh.

AWS Bedrock Titan — Python (boto3)

import boto3, json, base64

bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")

response = bedrock.invoke_model(
    modelId="amazon.titan-image-generator-v2:0",
    contentType="application/json",
    accept="application/json",
    body=json.dumps({
        "taskType": "TEXT_IMAGE",
        "textToImageParams": {"text": "A flowchart showing data flow from API to database"},
        "imageGenerationConfig": {
            "quality": "standard",
            "numberOfImages": 1,
            "height": 1024,
            "width": 1024,
            "cfgScale": 8.0,
        },
    }),
)

result = json.loads(response["body"].read())
with open("output.png", "wb") as f:
    f.write(base64.b64decode(result["images"][0]))

Bedrock Titan — Trustfile (Avalara)

For Trustfile AWS access, authenticate first then generate:

# 1. Get credentials (MFA via authenticator app)
gimme-aws-creds --profile trustfile-okta-admin

# 2. Generate image using the trustfile profile
AWS_PROFILE=trustfile scripts/bedrock-generate.sh "A diagram of a three-tier architecture"

# Or use the profile inline
AWS_PROFILE=trustfile aws bedrock-runtime invoke-model \
  --region us-east-1 \
  --model-id amazon.titan-image-generator-v2:0 \
  --content-type application/json \
  --accept application/json \
  --body fileb:///tmp/titan-request.json \
  /tmp/titan-response.json

API Reference

For full parameter details and response schemas, see references/api-reference.md.

Prompt Engineering for Diagrams

Image generation excels at creating diagrams, flowcharts, and conceptual models for documentation and courseware. Key principles:

Style Guide Pattern

Prepend a consistent style guide to every prompt for visual coherence across a set of images:

Flat vector illustration. Muted corporate palette: navy, orange, teal, gray, white.
Text labels are allowed for diagram annotations but use conservatively.
Prefer diagrams, flowcharts, and conceptual models over decorative art.
No faces — use abstract silhouettes. 16:9 aspect ratio. Clean negative space.

Effective Diagram Prompts

Good prompts describe the diagram structure, not just the concept:

# BAD — too abstract
"An image representing microservices architecture"

# GOOD — describes structure, labels, and layout
"A system architecture diagram with three labeled boxes arranged
horizontally: 'API Gateway' (left), 'Auth Service' (center),
'Database' (right). Arrows connect them left to right. Each box
has a small icon. Clean, minimal, labeled diagram."

Prompt Templates by Diagram Type

Text in Images

• Labels on diagram nodes, axes, and annotations: yes
• Repeating body text from the page: no
• Keep labels short (1-4 words per label)
• Use labels to clarify relationships the visual alone can't convey

Composite Diagrams (Mermaid/SVG + Titan Backgrounds)

When text rendering is critical (labeled diagrams, flowcharts, charts), use compositing instead of relying on AI image generators for text. Titan v2 cannot render readable text — it garbles all labels, axis text, and annotations.

Decision: Which Diagram Approach?

Pipeline Overview

Titan background (optional) ──→ ImageMagick dims to ~15-25% opacity
Mermaid .mmd OR hand-crafted SVG ──→ transparent PNG
ImageMagick ──→ composites layers + adds title/caption text ──→ final .webp

Requirements

brew install imagemagick librsvg
npm i -g @mermaid-js/mermaid-cli

Quick Start — compose-diagram.sh

# Diagram on solid dark background (no API call, instant)
scripts/compose-diagram.sh --mermaid diagram.mmd --title "My Diagram" --output slide.webp

# Diagram on Titan-generated background
AWS_PROFILE=trustfile scripts/compose-diagram.sh \
  --mermaid diagram.mmd \
  --bg-prompt "Abstract dark navy gradient with subtle particles" \
  --bg-opacity 0.15 \
  --title "The Baseline Loop" \
  --output slide.webp

# Diagram on existing background image
scripts/compose-diagram.sh \
  --mermaid diagram.mmd \
  --bg-image backgrounds/abstract-teal.png \
  --bg-opacity 0.20 \
  --output slide.webp

Options

Approach A: Mermaid Diagrams

Best for flowcharts, sequences, state machines, ER diagrams, mind maps. Embed theme in the .mmd:

%%{init: {'theme': 'base', 'themeVariables': {'background': 'transparent', 'mainBkg': '#1a3a4a', 'primaryColor': '#059bd2', 'primaryTextColor': '#f0f4f8', 'lineColor': '#7ab0c8', 'fontFamily': 'Helvetica Neue, Helvetica, Arial, sans-serif', 'fontSize': '24px'}}}%%
flowchart LR
    A["Frame"] --> B["Specify"] --> C["Generate"]
    style C fill:#fc6600,stroke:#e05800,color:#fff

Rules:

• fontSize: '24px' or larger (16px is too small for slides)
• background: 'transparent' required for compositing
• Explicit style for brand colors (orange #fc6600, navy #025979, teal #059bd2)
• mmdc renders via Puppeteer → system fonts work. Never use rsvg-convert for Mermaid (drops fonts).

Approach B: Hand-Crafted SVG

Best for charts, proportional visuals, and layouts Mermaid can't handle. Write an SVG file with the Avalara palette:

<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="500" viewBox="0 0 1200 500">
  <style>
    text { font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; }
    .title { font-size: 28px; fill: #f0f4f8; font-weight: 600; }
    .label { font-size: 18px; fill: #ffffff; font-weight: 500; }
  </style>
  <text x="600" y="40" text-anchor="middle" class="title">Chart Title</text>
  <rect x="200" y="70" width="200" height="315" rx="3" fill="#fc6600"/>
  <text x="300" y="230" text-anchor="middle" class="label">85%</text>
</svg>

Then composite manually:

# 1. Generate Titan background
AWS_PROFILE=trustfile scripts/bedrock-generate.sh \
  "Abstract dark navy gradient with subtle teal geometric lines" \
  bg.png --size 1408x768

# 2. Convert SVG → PNG
rsvg-convert -w 1200 diagram.svg -o diagram.png

# 3. Composite: dim bg + overlay diagram
magick bg.png -resize 1408x768! \
  \( +clone -fill "rgba(13,17,23,0.78)" -draw "rectangle 0,0 1408,768" \) -composite \
  \( diagram.png \) -gravity center -composite \
  output.webp

SVG color reference (Avalara brand):

• Navy: #025979 — borders, dark fills, verification segments
• Orange: #fc6600 — accents, implementation, CTAs
• Teal: #059bd2 — primary nodes, framing segments
• Light text: #f0f4f8 — labels on dark backgrounds
• Muted text: #a0b8c8 — axis labels, secondary text

Titan Background Prompts

Abstract only — never include text, charts, or diagrams in the prompt:

"Abstract dark navy gradient with subtle geometric patterns, minimal, moody"
"Deep teal and navy fluid waves, dark background, abstract, atmospheric"
"Dark gradient with soft glowing teal and orange particle dots, minimal"
"Subtle dark blueprint grid pattern, navy background, technical feel"

Titan prompt limit is 512 characters. Avoid words that trigger content filters ("dominated", etc.).

Available Themes

Pre-built Mermaid themes in scripts/mermaid-themes/:

• avalara-dark — Navy/teal/orange on dark (default)
• avalara-light — Navy/teal/orange on light

Manifest-Driven Batch Pipeline

For generating sets of images (e.g., course illustrations), use a JSON manifest:

{
  "meta": {
    "style_guide": "...",
    "default_size": "1024x576",
    "format": "webp"
  },
  "images": [
    {
      "module": "01-intro",
      "block_id": "overview",
      "prompt": "A hub-and-spoke diagram...",
      "alt": "System overview diagram",
      "filename": "01-overview.webp",
      "status": "pending"
    }
  ]
}

Status lifecycle: pending → generated → approved → integrated

A complete batch generation script is available at scripts/generate-images.ts. It supports:

• --provider openai|gemini
• --id <block_id> for single image
• --module <id> for one module
• --batch <n> for first n pending
• --model <name> to override default
• --dry-run to preview

Format Handling

Native WebP (OpenAI only)

OpenAI supports output_format: "webp" directly — no post-processing needed. Set output_compression (0-100) for quality control.

Converting PNG to WebP (Gemini)

Gemini outputs PNG. Convert with sharp:

import sharp from "sharp";

const webpBuffer = await sharp(pngBuffer).webp({ quality: 85 }).toBuffer();

Install: npm i -D sharp

Transparent Backgrounds (OpenAI only)

{ "background": "transparent", "output_format": "png" }

WebP also supports transparency, but PNG is more broadly compatible.

Error Handling

Cost Estimates

OpenAI (per image)

Gemini (per image)

For a 38-image course using OpenAI gpt-image-1 at medium quality: ~$2.66 total.