메인 콘텐츠로 건너뛰기
POST
Text-to-Image: generate image from text prompt
오른쪽의 대화형 플레이그라운드는 실시간 테스트를 지원합니다. Authorization에 API Key(형식: Bearer sk-xxx)를 입력하고, prompt를 작성한 후 크기 / 품질을 선택하여 전송합니다.
사용 사례: 이 페이지는 “텍스트-이미지”용입니다. prompt만 입력하면 되며 이미지를 업로드할 필요가 없습니다. 참조 이미지 편집, 다중 이미지 융합 또는 마스크 인페인팅에는 이미지 편집 엔드포인트를 사용합니다.
🖥️ 브라우저 플레이그라운드 제한 사항(중요)이 엔드포인트는 응답에서 원시 base64 문자열(일반적으로 수 MB)을 반환합니다. 브라우저 렌더링 제한으로 인해 오른쪽의 플레이그라운드에는 응답이 도착한 후 请求时发生错误: unable to complete request이 표시될 수 있습니다. 요청은 실제로 성공한 것이며, 브라우저에서 이렇게 긴 base64 문자열을 렌더링할 수 없을 뿐입니다.권장 워크플로(초보자용):
  • 아래의 Python / Node.js / cURL 샘플을 복사하여 로컬에서 실행합니다. 코드는 응답을 자동으로 base64.b64decodes 처리하고 이미지를 파일에 기록합니다.
  • 브라우저 내 플레이그라운드를 반드시 사용해야 한다면 size을 가장 작은 등급(예: 1024x1024)으로 설정하고, 응답 크기를 줄이도록 quality를 low으로 설정합니다.
모든 이미지 API는 동기식입니다. 폴링할 task ID가 없으며, 클라이언트 연결이 끊기면 요청에 대한 과금이 계속되는 동안 결과가 손실됩니다. 이 모델에는 충분히 긴 타임아웃을 설정하십시오. 이미지 API 필수 사항 및 모범 사례를 참조하십시오.
⚠️ 지원되지 않는 매개변수
  • input_fidelity — 세 모델 모두 고충실도를 강제하므로, 이를 전달하면 400을 반환합니다(2026-09-09에 2.5에서 확인됨: does not support the 'input_fidelity' parameter). 1.5에서 마이그레이션하는 경우 해당 줄을 제거하기만 하면 됩니다.
2560×1440 이상의 출력은 여전히 실험 단계입니다. 프로덕션 환경에서는 사전 설정인 2048x1152 / 2048x2048 / 3840x2160를 우선 사용하십시오.

코드 예제

Python (OpenAI SDK)

Python (원시 요청)

cURL

Node.js (네이티브 fetch)

브라우저 JavaScript (직접 렌더링)

매개변수 참조

quality에 기존 DALL·E 값인 standard / hd을(를) 전달하지 마십시오. 오직 6개의 공식 enum 값인 low / medium / high / xhigh / max / auto만 허용됩니다(xhigh / max은(는) 두 2.5 모델에서만 허용됨). 레거시 값은 백엔드 채널에 따라 일관되지 않게 동작합니다. 때로는 400(invalid_value) 오류와 함께 즉시 실패하고, 때로는 자동으로 무시되어 요청이 auto(으)로 실행되기도 합니다(예측할 수 없는 비용 발생). 항상 공식 값 중 하나를 명시적으로 전달하십시오.
자세한 제약 조건, 허용되는 값 및 예시는 오른쪽 Playground에서 확인할 수 있습니다. 모든 enum 필드는 드롭다운 선택을 지원합니다.

응답 형식

⚠️ b64_json은 원시 base64입니다, data:image/...;base64, 접두사 없이입니다. 클라이언트는 다음을 수행해야 합니다:
  • 파일 쓰기: base64.b64decode(b64_str) → 디스크에 기록
  • 브라우저 렌더링: data:image/png;base64,을 수동으로 앞에 붙입니다
2026년 7월 기준, gpt-image-2-all / gpt-image-2-vip도 원시 base64를 반환하지만, 이전 버전에는 접두사가 포함되어 있었습니다 — 모델 간에 코드를 공유할 때는 항상 먼저 startsWith('data:')를 확인하십시오.
usage 필드는 이 호출에 대해 실제로 과금된 token 수를 나타냅니다. input_tokens_details / output_tokens_details은 텍스트 token과 이미지 token을 별도로 분리합니다(image_tokens은 일반 text-to-image의 경우 항상 0입니다). 전체 필드 참고와 셀프서비스 비용 계산 공식은 개요 페이지의 각 호출의 실제 token 수를 확인하는 방법을 참조하십시오.

인증

Authorization
string
header
필수

API Key obtained from APIYI Console

본문

application/json
model
enum<string>
기본값:gpt-image-2.5-flare
필수

Model name. gpt-image-2.5-flare (speed-first) / gpt-image-2.5-sunburst (quality- and editing-first) / gpt-image-2 (previous generation) share the same price and parameters; pin a dated snapshot in production

사용 가능한 옵션:
gpt-image-2.5-flare,
gpt-image-2.5-sunburst,
gpt-image-2,
gpt-image-2.5-flare-2026-09-08,
gpt-image-2.5-sunburst-2026-09-08
prompt
string
필수

Prompt text, up to 32,000 characters (provider limit, counted in characters). Supports both Chinese and English. Place scene description at the front for better adherence.

Maximum string length: 32000
예시:

"Cyberpunk city at night, neon sign closeup, cinematic frame"

size
string
기본값:auto

Output size. Presets: 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840. Also accepts any valid custom size (max edge ≤ 3840, both multiples of 16, ratio ≤ 3:1, total pixels 0.65–8.3MP).

예시:

"2048x1152"

quality
enum<string>
기본값:auto

Quality tier. low (sketches/batch), medium (daily), high (final/fine text), xhigh / max (new in 2.5: higher quality and cost, rejected by gpt-image-2), auto (default)

사용 가능한 옵션:
auto,
low,
medium,
high,
xhigh,
max
output_format
enum<string>
기본값:png

Output format

사용 가능한 옵션:
png,
jpeg,
webp
output_compression
integer

Output compression (0–100), only effective for jpeg/webp

필수 범위: 0 <= x <= 100
예시:

85

background
enum<string>
기본값:auto

Background mode. auto (default) / opaque / transparent. transparent requires png or webp (jpeg has no alpha channel)

사용 가능한 옵션:
auto,
opaque,
transparent
moderation
enum<string>
기본값:auto

Moderation strength. auto (default) or low

사용 가능한 옵션:
auto,
low
n
enum<integer>
기본값:1

Number of images. This model only supports 1

사용 가능한 옵션:
1

응답

Image generated successfully

created
integer

Unix timestamp

예시:

1776832476

data
object[]

Generation results (this model returns 1 image per call)

usage
object

Token usage for this call (used for token-based billing)