이미지 생성

이미지 생성 (Image Generation)

generateImage 함수를 사용해 이미지 모델로 프롬프트 기반의 이미지를 생성하는 방법을 설명하는 문서예요.

출처: 문서

본문

AI SDK는 이미지 모델을 사용해 주어진 프롬프트를 기반으로 이미지를 생성하는 generateImage 함수를 제공해요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
});

base64 또는 uint8Array 속성을 사용해 이미지 데이터에 접근할 수 있어요:

const base64 = image.base64; // base64 image data
const uint8Array = image.uint8Array; // Uint8Array image data

설정 (Settings)

크기와 종횡비 (Size and Aspect Ratio)

모델에 따라 크기(size) 또는 종횡비(aspect ratio)를 지정할 수 있어요.

크기 (Size)

크기는 {width}x{height} 형식의 문자열로 지정해요. 모델은 몇 가지 크기만 지원하며, 지원되는 크기는 모델과 프로바이더마다 달라요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  size: '1024x1024',
});
종횡비 (Aspect Ratio)

종횡비는 {width}:{height} 형식의 문자열로 지정해요. 모델은 몇 가지 종횡비만 지원하며, 지원되는 종횡비는 모델과 프로바이더마다 달라요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  aspectRatio: '16:9',
});

여러 이미지 생성 (Generating Multiple Images)

generateImage는 한 번에 여러 이미지 생성을 지원해요:

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { images } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  n: 4, // number of images to generate
});

참고: generateImage는 요청된 수의 이미지를 생성하기 위해 필요할 때마다 모델을 자동으로 (병렬로) 호출해요.

각 이미지 모델은 단일 API 호출에서 생성할 수 있는 이미지 수에 내부 제한이 있어요. AI SDK는 n 매개변수로 여러 이미지를 요청할 때 요청을 적절히 배치함으로써 이를 자동으로 관리해요. 기본적으로 SDK는 프로바이더가 문서화한 제한을 사용해요 (예: DALL-E 3는 호출당 1개만, DALL-E 2는 최대 10개 지원).

필요하다면 이미지를 생성할 때 maxImagesPerCall 설정으로 이 동작을 오버라이드할 수 있어요. 이는 기본 배치 크기가 최적이 아닐 수 있는 새 모델이나 커스텀 모델로 작업할 때 특히 유용해요:

const { images } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  maxImagesPerCall: 5, // Override the default batch size
  n: 10, // Will make 2 calls of 5 images each
});

시드 제공 (Providing a Seed)

generateImage 함수에 seed를 제공해 이미지 생성 과정의 출력을 제어할 수 있어요. 모델이 지원하면 같은 seed는 항상 같은 이미지를 만들어요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  seed: 1234567890,
});

프로바이더별 설정 (Provider-specific Settings)

이미지 모델은 종종 프로바이더, 심지어 모델별 설정을 갖고 있어요. providerOptions 매개변수를 사용해 이러한 설정을 generateImage 함수에 전달할 수 있어요. 프로바이더(아래 예제의 openai)에 대한 옵션은 요청 본문 속성이 돼요.

import { generateImage } from 'ai';
import { openai, type OpenAIImageModelGenerationOptions } from '@ai-sdk/openai';

const { image } = await generateImage({
  model: openai.image('dall-e-3'),
  prompt: 'Santa Claus driving a Cadillac',
  size: '1024x1024',
  providerOptions: {
    openai: {
      style: 'vivid',
      quality: 'hd',
    } satisfies OpenAIImageModelGenerationOptions,
  },
});

중단 신호와 타임아웃 (Abort Signals and Timeouts)

generateImage는 AbortSignal 타입의 선택적 abortSignal 매개변수를 받으며, 이미지 생성 과정을 중단하거나 타임아웃을 설정하는 데 사용할 수 있어요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  abortSignal: AbortSignal.timeout(1000), // Abort after 1 second
});

커스텀 헤더 (Custom Headers)

generateImage는 타입 Record<string, string>의 선택적 headers 매개변수를 받으며, 이미지 생성 요청에 커스텀 헤더를 추가하는 데 사용할 수 있어요.

import { generateImage } from 'ai';
__PROVIDER_IMPORT__;

const { image } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
  headers: { 'X-Custom-Header': 'custom-value' },
});

경고 (Warnings)

모델이 지원되지 않는 매개변수에 대한 경고 같은 경고를 반환하면, 응답의 warnings 속성에서 사용할 수 있어요.

const { image, warnings } = await generateImage({
  model: __IMAGE_MODEL__,
  prompt: 'Santa Claus driving a Cadillac',
});

프로바이더 메타데이터 (Provider metadata)

일부 프로바이더는 개별 이미지에 대한 메타데이터를 노출해요. 이는 생성된 이미지에서 직접 사용할 수 있어요:

const prompt = 'Santa Claus driving a Cadillac';

const { image } = await generateImage({
  model: openai.image('dall-e-3'),
  prompt,
});

const revisedPrompt = image.providerMetadata?.openai?.revisedPrompt;

console.log({
  prompt,
  revisedPrompt,
});

image.providerMetadata의 바깥 키는 프로바이더 이름이에요. 안쪽 값은 그 이미지에 대한 메타데이터예요.

내부 호출 (Underlying calls)

요청이 여러 프로바이더 호출로 분할되면 calls는 각 호출의 이미지, 프로바이더 메타데이터, 응답 메타데이터, 경고, 사용량을 보존해요. images와 usage는 각각 편리한 평탄화된 뷰와 집계 뷰로 남아 있어요.

const { calls } = await generateImage({
  model,
  prompt: 'Santa Claus driving a Cadillac',
  n: 4,
  maxImagesPerCall: 1,
});

for (const call of calls) {
  console.log(call.providerMetadata, call.usage);
}

오류 처리 (Error Handling)

generateImage가 유효한 이미지를 생성하지 못하면 AI_NoImageGeneratedError를 던져요. 분류되지 않은 빈 이미지 응답은 이 오류가 던져지기 전에 maxRetries에 따라 재시도돼요. 프로바이더는 moderation 블록 같은 종료 상태의 빈 응답을 isRetryable: false로 분류할 수 있으며, 이러한 응답은 재시도되지 않아요.

이 오류는 AI 프로바이더가 이미지를 생성하지 못할 때 발생해요. 다음 이유 때문에 발생할 수 있어요:

  • 모델이 응답을 생성하지 못함
  • 모델이 파싱할 수 없는 응답을 생성함

이 오류는 문제를 로깅하는 데 도움이 되도록 다음 정보를 보존해요:

  • calls: 생성된 이미지, 프로바이더 메타데이터, 응답 메타데이터, 경고, 사용량을 포함한 내부 이미지 모델 호출의 결과.
  • responses: 타임스탬프, 모델, 헤더를 포함한 이미지 모델 응답에 대한 메타데이터.
  • cause: 오류의 원인. 더 상세한 오류 처리를 위해 사용할 수 있어요.
import { generateImage, NoImageGeneratedError } from 'ai';

try {
  await generateImage({ model, prompt });
} catch (error) {
  if (NoImageGeneratedError.isInstance(error)) {
    console.log('NoImageGeneratedError');
    console.log('Cause:', error.cause);
    console.log('Responses:', error.responses);

    for (const call of error.calls ?? []) {
      console.log('Provider metadata:', call.providerMetadata);
      console.log('Warnings:', call.warnings);
      console.log('Usage:', call.usage);
    }
  }
}

이미지 미들웨어 (Image Middleware)

wrapImageModel과 ImageModelV4Middleware를 사용해 이미지 모델을 향상시킬 수 있어요. 예를 들어 기본값을 설정하거나 로깅을 구현할 수 있어요.

값이 제공되지 않을 때 기본 크기를 설정하는 예제는 다음과 같아요:

import { generateImage, wrapImageModel } from 'ai';
__PROVIDER_IMPORT__;

const model = wrapImageModel({
  model: __IMAGE_MODEL__,
  middleware: {
    specificationVersion: 'v3',
    transformParams: async ({ params }) => ({
      ...params,
      size: params.size ?? '1024x1024',
    }),
  },
});

const { image } = await generateImage({
  model,
  prompt: 'Santa Claus driving a Cadillac',
});

언어 모델로 이미지 생성 (Generating Images with Language Models)

Google gemini-3.1-flash-image-preview 같은 일부 언어 모델은 이미지를 포함한 멀티모달 출력을 지원해요. 이러한 모델에서는 응답의 files 속성으로 생성된 이미지에 접근할 수 있어요.

import { google } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: google('gemini-3.1-flash-image-preview'),
  prompt: 'Generate an image of a comic cat',
});

for (const file of result.files) {
  if (file.mediaType.startsWith('image/')) {
    // The file object provides multiple data formats:
    // Access images as base64 string, Uint8Array binary data, or check type
    // - file.base64: string (data URL format)
    // - file.uint8Array: Uint8Array (binary data)
    // - file.mediaType: string (e.g. "image/png")
  }
}

이미지 모델 (Image Models)

프로바이더 모델 지원 크기 (width x height) 또는 종횡비 (width : height)
xAI Grok grok-imagine-image 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto
OpenAI gpt-image-2.5-flare 1024x1024, 1536x1024, 1024x1536, custom
OpenAI gpt-image-2.5-sunburst 1024x1024, 1536x1024, 1024x1536, custom
OpenAI gpt-image-2 1024x1024, 1536x1024, 1024x1536
OpenAI dall-e-3 1024x1024, 1792x1024, 1024x1792
OpenAI dall-e-2 256x256, 512x512, 1024x1024
Amazon Bedrock amazon.nova-canvas-v1:0 320-4096 (16의 배수), 1:4 ~ 4:1, 최대 4.2M 픽셀
Fal fal-ai/flux/dev 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/flux-lora 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/fast-sdxl 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/flux-pro/v1.1-ultra 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/ideogram/v2 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/recraft-v3 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/stable-diffusion-3.5-large 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Fal fal-ai/hyper-sdxl 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
DeepInfra stabilityai/sd3.5 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21
DeepInfra black-forest-labs/FLUX-1.1-pro 256-1440 (32의 배수)
DeepInfra black-forest-labs/FLUX-1-schnell 256-1440 (32의 배수)
DeepInfra black-forest-labs/FLUX-1-dev 256-1440 (32의 배수)
DeepInfra black-forest-labs/FLUX-pro 256-1440 (32의 배수)
DeepInfra stabilityai/sd3.5-medium 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21
DeepInfra stabilityai/sdxl-turbo 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21
Replicate black-forest-labs/flux-schnell 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9
Replicate recraft-ai/recraft-v3 1024x1024, 1365x1024, 1024x1365, 1536x1024, 1024x1536, 1820x1024, 1024x1820, 1024x2048, 2048x1024, 1434x1024, 1024x1434, 1024x1280, 1280x1024, 1024x1707, 1707x1024
Google gemini-2.5-flash-image 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Google gemini-3-pro-image-preview 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Google gemini-3.1-flash-image-preview 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Google Vertex gemini-2.5-flash-image 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Google Vertex gemini-3-pro-image-preview 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Google Vertex gemini-3.1-flash-image-preview 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Fireworks accounts/fireworks/models/flux-1-dev-fp8 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9
Fireworks accounts/fireworks/models/flux-1-schnell-fp8 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9
Fireworks accounts/fireworks/models/playground-v2-5-1024px-aesthetic 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640
Fireworks accounts/fireworks/models/japanese-stable-diffusion-xl 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640
Fireworks accounts/fireworks/models/playground-v2-1024px-aesthetic 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640
Fireworks accounts/fireworks/models/SSD-1B 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640
Fireworks accounts/fireworks/models/stable-diffusion-xl-1024-v1-0 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640
Luma photon-1 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Luma photon-flash-1 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9
Together.ai stabilityai/stable-diffusion-xl-base-1.0 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-dev 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-dev-lora 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-schnell 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-canny 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-depth 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-redux 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1.1-pro 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-pro 512x512, 768x768, 1024x1024
Together.ai black-forest-labs/FLUX.1-schnell-Free 512x512, 768x768, 1024x1024
Black Forest Labs flux-kontext-pro 3:7(세로) ~ 7:3(가로)
Black Forest Labs flux-kontext-max 3:7(세로) ~ 7:3(가로)
Black Forest Labs flux-pro-1.1-ultra 3:7(세로) ~ 7:3(가로)
Black Forest Labs flux-pro-1.1 3:7(세로) ~ 7:3(가로)
Black Forest Labs flux-pro-1.0-fill 3:7(세로) ~ 7:3(가로)

위는 AI SDK 프로바이더가 지원하는 이미지 모델의 일부일 뿐이에요. 더 많은 내용은 각 프로바이더 문서를 참고하세요.

더 알아보기 (Learn more)