图像生成

TanStack AI 通过专用的图像适配器提供图像生成支持。本指南介绍如何使用 OpenAI 和 Gemini 提供商的图像生成功能。

概述

图像生成由遵循与 TanStack AI 中的其他适配器相同的可摇树架构的图像适配器处理。图像适配器支持

OpenAI：DALL-E 2、DALL-E 3、GPT-Image-1 和 GPT-Image-1-Mini 模型
Gemini：Imagen 3 和 Imagen 4 模型

基本用法

OpenAI 图像生成

typescript

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

// Create an image adapter (uses OPENAI_API_KEY from environment)
const adapter = openaiImage()

// Generate an image
const result = await generateImage({
  adapter: openaiImage('dall-e-3'),
  prompt: 'A beautiful sunset over mountains',
})

console.log(result.images[0].url) // URL to the generated image

Gemini 图像生成

typescript

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

// Create an image adapter (uses GOOGLE_API_KEY from environment)
const adapter = geminiImage()

// Generate an image
const result = await generateImage({
  adapter: geminiImage('imagen-3.0-generate-002'),
  prompt: 'A futuristic cityscape at night',
})

console.log(result.images[0].b64Json) // Base64 encoded image

选项

通用选项

所有图像适配器都支持这些通用选项

选项	类型	描述
adapter	ImageAdapter	带有模型的图像适配器实例（必需）
prompt	string	要生成的图像的文本描述（必需）
numberOfImages	number	要生成的图像数量
size	string	生成的图像大小，格式为 WIDTHxHEIGHT
modelOptions?	object	特定于模型的选项（重命名自 providerOptions）

尺寸选项

OpenAI 模型

模型	支持的尺寸
gpt-image-1	1024x1024、1536x1024、1024x1536、auto
gpt-image-1-mini	1024x1024、1536x1024、1024x1536、auto
dall-e-3	1024x1024、1792x1024、1024x1792
dall-e-2	256x256、512x512、1024x1024

Gemini 模型

Gemini 内部使用纵横比，但 TanStack AI 接受 WIDTHxHEIGHT 格式并进行转换

尺寸	纵横比
1024x1024	1:1
1920x1080	16:9
1080x1920	9:16

或者，您可以在模型选项中直接指定纵横比

typescript

const result = await generateImage({
  adapter: geminiImage('imagen-4.0-generate-001'),
  prompt: 'A landscape photo',
  modelOptions: {
    aspectRatio: '16:9'
  }
})

模型选项

OpenAI 模型选项

OpenAI 模型支持特定于模型的模型选项

GPT-Image-1 / GPT-Image-1-Mini

typescript

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

DALL-E 3

typescript

const result = await generateImage({
  adapter: openaiImage('dall-e-3'),
  prompt: 'A futuristic car',
  modelOptions: {
    quality: 'hd', // 'hd' | 'standard'
    style: 'vivid', // 'vivid' | 'natural'
  }
})

Gemini 模型选项

typescript

const result = await generateImage({
  adapter: geminiImage('imagen-4.0-generate-001'),
  prompt: 'A beautiful garden',
  modelOptions: {
    aspectRatio: '16:9',
    personGeneration: 'ALLOW_ADULT', // 'DONT_ALLOW' | 'ALLOW_ADULT' | 'ALLOW_ALL'
    negativePrompt: 'blurry, low quality',
    addWatermark: true,
    outputMimeType: 'image/png', // 'image/png' | 'image/jpeg' | 'image/webp'
  }
})

响应格式

图像生成结果包括

typescript

interface ImageGenerationResult {
  id: string // Unique identifier for this generation
  model: string // The model used
  images: GeneratedImage[] // Array of generated images
  usage?: {
    inputTokens: number
    outputTokens: number
    totalTokens: number
  }
}

interface GeneratedImage {
  b64Json?: string // Base64 encoded image data
  url?: string // URL to the image (OpenAI only)
  revisedPrompt?: string // Revised prompt (OpenAI only)
}

模型可用性

OpenAI 模型

模型	每请求图像数
gpt-image-1	1-10
gpt-image-1-mini	1-10
dall-e-3	1
dall-e-2	1-10

Gemini 模型

模型	每请求图像数
imagen-3.0-generate-002	1-4
imagen-4.0-generate-001	1-4
imagen-4.0-fast-generate-001	1-4
imagen-4.0-ultra-generate-001	1-4

错误处理

图像生成可能由于各种原因而失败。适配器在进行 API 调用之前会验证输入

typescript

try {
  const result = await generateImage({
    adapter: openaiImage('dall-e-3'),
    prompt: 'A cat',
    size: '512x512', // Invalid size for DALL-E 3
  })
} catch (error) {
  console.error(error.message)
  // "Size "512x512" is not supported by model "dall-e-3". 
  //  Supported sizes: 1024x1024, 1792x1024, 1024x1792"
}

环境变量

图像适配器使用与文本适配器相同的环境变量

OpenAI：OPENAI_API_KEY
Gemini：GOOGLE_API_KEY 或 GEMINI_API_KEY

显式 API 密钥

对于生产用途或需要显式控制时

typescript

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

// OpenAI
const openaiAdapter = createOpenaiImage('your-openai-api-key')

// Gemini
const geminiAdapter = createGeminiImage('your-google-api-key')