Image Generation: Advanced

size: '16:9_4K' // widescreen at 4K
size: '1:1_2K' // square at 2K
size: '1:8_512' // tall banner at the 512 tier, gemini-3.1-flash-image only

import { generateImage } from '@tanstack/ai'
import { openaiImage } from '@tanstack/ai-openai'

const result = await generateImage({
  adapter: openaiImage('gpt-image-2.5-flare'),
  prompt: 'A cat wearing a hat',
  threadId: 'thread-1',
  modelOptions: {
    quality: 'high', // 'high' | 'medium' | 'low' | 'auto'
    background: 'transparent', // 'transparent' | 'opaque' | 'auto'
    output_format: 'png', // 'png' | 'jpeg' | 'webp'
    moderation: 'low', // 'low' | 'auto'
  },
})

import { generateImage } from '@tanstack/ai'
import { geminiImage, ThinkingLevel } from '@tanstack/ai-gemini'

const result = await generateImage({
  adapter: geminiImage('gemini-nano-banana-2.1'),
  prompt: 'A beautiful garden',
  threadId: 'thread-1',
  size: '16:9_4K',
  modelOptions: {
    seed: 42,
    thinkingConfig: { thinkingLevel: ThinkingLevel.LOW },
    systemInstruction: 'Always render in watercolor.',
    // imageConfig replaces one field from size. The 16:9 ratio from size stays.
    // imageConfig accepts only aspectRatio and imageSize.
    imageConfig: { imageSize: '2K' },
  },
})

import { generateImage } from '@tanstack/ai'
import {
  HarmBlockThreshold,
  HarmCategory,
  geminiImage,
} from '@tanstack/ai-gemini'

const result = await generateImage({
  adapter: geminiImage('gemini-nano-banana-2.1'),
  prompt: 'A beautiful garden',
  threadId: 'thread-1',
  modelOptions: {
    safetySettings: [
      {
        category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
        threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
      },
    ],
  },
})

// URL source
{ type: 'image', source: { type: 'url', value: 'https://example.com/img.png' } }

// Inline base64 data (mimeType is required)
{ type: 'image', source: { type: 'data', value: base64String, mimeType: 'image/png' } }

import { createOpenaiImage } from '@tanstack/ai-openai'

const apiKey = process.env.OPENAI_API_KEY ?? ''

// Download and buffer HTTP(S) URL image inputs.
const adapter = createOpenaiImage('gpt-image-2.5-flare', apiKey, {
  allowUrlFetch: true,
})

import { generateImage } from '@tanstack/ai'
import { openaiImage } from '@tanstack/ai-openai'
import { photoUrl, maskUrl } from './urls'

await generateImage({
  adapter: openaiImage('gpt-image-2.5-flare'),
  prompt: [
    { type: 'text', content: 'Replace the masked region with a tree' },
    { type: 'image', source: { type: 'url', value: photoUrl } },
    {
      type: 'image',
      source: { type: 'url', value: maskUrl },
      metadata: { role: 'mask' },
    },
  ],
  threadId: 'thread-1',
})

import { generateImage } from '@tanstack/ai'
import { geminiImage } from '@tanstack/ai-gemini'

await generateImage({
  adapter: geminiImage('gemini-nano-banana-2.1'),
  prompt: [
    {
      type: 'text',
      content:
        'Generate a new image of the product using the style of the second reference',
    },
    {
      type: 'image',
      source: { type: 'url', value: 'https://example.com/product.png' },
    },
    {
      type: 'image',
      source: { type: 'url', value: 'https://example.com/style.png' },
    },
  ],
  threadId: 'thread-1',
})

import { generateImage } from '@tanstack/ai'
import { geminiImage } from '@tanstack/ai-gemini'
import { badExampleUrl, goodExampleUrl } from './urls'

await generateImage({
  adapter: geminiImage('gemini-nano-banana-2.1'),
  prompt: [
    { type: 'text', content: 'Not like this' },
    { type: 'image', source: { type: 'url', value: badExampleUrl } },
    { type: 'text', content: 'more like this' },
    { type: 'image', source: { type: 'url', value: goodExampleUrl } },
  ],
  threadId: 'thread-1',
})

import type { TokenUsage } from '@tanstack/ai'

interface ImageGenerationResult {
  id: string // unique id for this generation
  model: string // the model used
  images: GeneratedImage[] // the generated images
  // Same TokenUsage shape as chat. Token-billed models also add a breakdown
  // per modality on `promptTokensDetails` (for example text and image input
  // tokens for gpt-image-1). fal sets `usage.billed` instead.
  usage?: TokenUsage
}

interface GeneratedImage {
  b64Json?: string // base64 image data
  url?: string // URL of the image
  revisedPrompt?: string // revised prompt (OpenAI only)
}

import { generateImage } from '@tanstack/ai'
import { falImage } from '@tanstack/ai-fal'
import { unitPrice } from './pricing'

const result = await generateImage({
  adapter: falImage('fal-ai/flux/dev'),
  prompt: 'a serene mountain lake',
  threadId: 'thread-1',
})

if (result.usage?.billed) {
  const { quantity, unit } = result.usage.billed
  const cost = quantity * unitPrice // unitPrice from the fal pricing API
  console.log(`Billed ${quantity} ${unit} (~$${cost})`)
}

import { generateImage } from '@tanstack/ai'
import { openaiImage } from '@tanstack/ai-openai'

try {
  const result = await generateImage({
    adapter: openaiImage('gpt-image-2.5-flare'),
    prompt: 'A cat',
    threadId: 'thread-1',
    size: '512x512', // not a gpt-image-2.5-flare size, throws at runtime
  })
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message)
    // "Size "512x512" is not supported by model "gpt-image-2.5-flare".
    //  Supported sizes: 1024x1024, 1536x1024, 1024x1536, auto"
  }
}

import { createOpenaiImage } from '@tanstack/ai-openai'
import { createGeminiImage } from '@tanstack/ai-gemini'

const openaiAdapter = createOpenaiImage('gpt-image-2.5-flare', 'your-openai-api-key')

const geminiAdapter = createGeminiImage(
  'gemini-nano-banana-2.1',
  'your-google-api-key',
)