OpenAI는 Image API (POST /images/generations)을 통해 이미지 생성을 제공합니다. 공식 openai npm 패키지는 이를 client.images.generate로 래핑(wrap)합니다. 이 게시물에서는 주요 요청 매개변수와 Node.js에서 생성된 이미지를 저장하는 방법을 안내합니다.

예제에서는 OpenAI의 최신 GPT Image 모델인 **gpt-image-2**를 사용합니다. GPT Image 모델은 항상 data[].b64_json에 base64로 인코딩된 이미지 데이터를 반환합니다. 디스크 파일 유형에는 output_format을 사용하고, 예술적 방향(artistic direction)은 프롬프트에 포함하세요.

동일한 패키지를 사용하여 텍스트 생성을 하려면 Chat Completions API와 Responses API 게시물을 참조하세요. 이미지 생성은 Responses API 도구를 통해서도 가능하지만, 이 게시물에서는 전용 Image API 엔드포인트에 초점을 맞춥니다.

실행 시나리오: 가상의 투두 앱을 위한 마케팅 히어로 이미지를 생성합니다.

사전 준비 사항 (Prerequisites)

• OpenAI 계정
• 생성된 API 키
• 활성화된 결제(billing)
• Node.js 버전 26
• openai 패키지 설치 (npm i openai)

클라이언트 설정 (Client setup)

API 키로 클라이언트를 생성합니다 (운영 환경에서는 환경 변수에서 읽어옵니다).

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

동일한 SDK는 baseURL과 apiKey를 설정하여 호환 가능한 API를 구현하는 다른 호스트도 대상으로 할 수 있습니다:

const client = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://your-gateway.example/v1',
...

Azure OpenAI는 대신 AzureOpenAI를 사용합니다. 제공업체가 Image API와 model에 전달하는 모델을 지원하는지 확인하세요.

기본 통합 (Basic integration)

모델과 프롬프트를 사용하여 client.images.generate를 호출하세요. 예시에서는 gpt-image-2가 사용되었으며, 이전 스냅샷으로는 gpt-image-1.5, gpt-image-1, 그리고 gpt-image-1-mini가 포함됩니다. 배포 간 안정적인 동작이 필요할 때는 스냅샷(예: gpt-image-2-2026-04-21)을 고정하세요.

prompt는 무엇을 생성할지 설명합니다. GPT Image 모델은 최대 약 32,000자의 프롬프트를 허용합니다. 주제, 레이아웃, 색상 및 스타일에 대해 구체적으로 작성하세요.

GPT Image 모델은 항상 data[].b64_json에 base64 형태로 반환됩니다. 이를 디코딩하여 직접 파일을 작성해야 합니다.

import { writeFile } from 'node:fs/promises';

const prompt = `
...

n

n을 사용하여 한 요청으로 여러 이미지를 생성하세요(기본값 1, 최대 10). 각 이미지를 저장하려면 result.data를 반복하세요.

import { writeFile } from 'node:fs/promises';

const result = await client.images.generate({
...

Size

size로 크기를 제어할 수 있습니다. 일반적인 사전 설정은 1024x1024(정사각형), 1536x1024(가로), 그리고 1024x1536(세로)입니다. auto는 모델이 프롬프트를 기반으로 선택하도록 합니다.

gpt-image-2는 너비와 높이가 16의 배수이고, 종횡비가 1:3과 3:1 사이이며, 총 픽셀 수가 문서화된 제한 내에 있는 경우 사용자 지정 WIDTHxHEIGHT 문자열도 허용합니다.

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
...

Quality

quality로 렌더링 품질을 설정하세요. 빠른 초안 및 반복 작업에는 low를 사용하고, 최종 에셋에는 medium 또는 high를 사용하세요. 기본값은 auto입니다.

const draft = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
...

Output format

GPT Image 모델은 JSON 응답에 base64 형태로 반환됩니다. output_format을 사용하여 인코딩된 파일 유형을 제어하세요: png(기본값), jpeg, 또는 webp.

import { writeFile } from 'node:fs/promises';

const result = await client.images.generate({
...

Compression

압축 (Compression)

output_format이 jpeg 또는 webp인 경우, output_compression을 0에서 100 사이로 설정하여 파일 크기와 품질을 조절할 수 있습니다. 지연 시간 (Latency)이 중요한 경우에는 JPEG가 PNG보다 빠른 경우가 많습니다.

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt: '...'
});

배경 (Background)

누끼 이미지 (Cutout asset)가 필요한 경우, 이를 지원하는 모델에서 png 또는 webp와 함께 background: 'transparent'를 사용하세요. gpt-image-2는 투명 배경을 지원하지 않습니다. 해당 워크플로우를 위해서는 gpt-image-1.5 또는 이전 버전의 GPT Image 모델을 사용하거나, 프롬프트에 배경을 포함하여 생성하세요.

const result = await client.images.generate({
  model: 'gpt-image-1.5',
  prompt: 'Flat icon of a checkmark, no background, centered',
  ... 
});

프로덕션 참고 사항 (Production notes)

• 비용 (Cost): quality 및 size에 따라 비례하여 증가합니다. 대규모 생성 전에는 OpenAI pricing을 확인하세요.
• 모더레이션 (Moderation): 필터링 제한을 완화해야 하는 경우, GPT Image 모델에서 moderation: 'auto' (기본값) 또는 'low'를 사용하세요.
• 오류 (Errors): image_generation_user_error (예: moderation_blocked)가 발생하면 프롬프트나 입력을 변경하여 처리하세요. 무작정 재시도하지 마십시오.
• 지연 시간 (Latency): 복잡한 프롬프트는 최대 약 2분까지 소요될 수 있습니다.
• 저장 (Storage): 파일을 직접 디코딩하고 영구 저장해야 합니다. GPT Image 응답은 JSON 내의 base64 형식입니다.

데모 (Demo)

각 섹션에 대한 실행 가능한 스크립트는 openai-image-generation-demo 폴더에 있습니다. code demos를 통해 접속할 수 있습니다.