API

GPT Image 2.5 API

이미지

GPT Image 2.5 API로 OpenAI의 가장 발전된 이미지 생성 및 편집 모델을 앱에 도입하세요. 텍스트로 이미지를 생성하거나 참조 이미지를 편집할 수 있으며, 다양한 종횡비와 1K, 2K, 4K 출력을 지원합니다. 빠르고 고품질인 일상적인 생성에는 flare를, 높은 품질이 필요한 창작 작업과 정밀한 편집에는 sunburst를 선택하세요.

인증

Bearerstringheader필수

요청 인증용 API 키

본문

application/json

modelstring필수

gpt-image-2-5

input.promptstring필수

생성하려는 이미지의 피사체, 구도, 스타일, 조명을 설명하세요. 이미지를 편집할 때는 참조 이미지에서 변경할 부분과 유지할 부분을 지정하세요. 앞뒤 공백은 제거됩니다.

input.modestring선택

GPT Image 2.5 모델을 선택합니다. flare는 기본 모드이며, 고품질의 일상적인 이미지 생성과 빠른 반복 작업을 위해 속도를 우선합니다. sunburst는 높은 품질 요구 사항과 편집 정밀도를 우선하며, 참조 이미지를 정확하게 수정해야 하는 작업에 적합합니다.

두 모드 모두 텍스트 기반 이미지 생성과 이미지 편집을 지원합니다. 텍스트로 생성하려면 input.images를 생략하고, 편집하려면 참조 이미지를 제공하세요. 모드를 비교할 때는 동일한 프롬프트, 참조 이미지, 종횡비, 해상도를 사용하세요.

기본값: flare

flaresunburst

input.imagesstring[]선택

선택적 참조 이미지 URL 목록입니다. 공개적으로 접근 가능한 HTTPS URL만 사용하세요. 텍스트로 이미지를 생성할 때는 생략하세요.

input.aspect_ratiostring선택

출력 이미지의 너비와 높이 비율입니다. auto는 모델이 적절한 구도를 선택하도록 합니다. 목록에서 비율을 선택해 형식을 지정하세요. 예: 정사각형 1:1, 세로형 9:16, 가로형 16:9.

기본값: auto

auto1:12:33:23:44:39:1616:921:9

input.resolutionstring선택

출력 해상도 단계입니다. 소문자 값 1k, 2k, 4k로 원하는 단계를 선택하세요. 특정 출력 해상도가 필요하면 이 필드를 명시적으로 설정하세요.

기본값: 2k

1k2k4k

요청 예제

POST /api/v1/create

curl -X POST https://nanobanana.io/api/v1/create \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2-5",
  "input": {
    "prompt": "미래형 바나나 모양 카메라를 담은 시네마틱 제품 사진"
  }
}'

POST /api/v1/create · HTTP 201

{
  "data": {
    "task_id": "task_example",
    "model": "gpt-image-2-5",
    "status": "processing",
    "credits": 5
  }
}

반환된 작업 ID를 사용해 작업이 완료되거나 실패할 때까지 이 엔드포인트를 폴링하세요. 최신 작업 상태를 확인하려면 5초마다 폴링하는 것을 권장합니다.

POST /api/v1/check

{
  "task_id": "task_example"
}

응답

POST /api/v1/check가 반환하는 작업 상태입니다. 아래 ID, URL, 타임스탬프는 예시입니다.

idstring필수

data.id는 작업 식별자로, 조회 요청의 task_id와 같습니다.

statusstring필수

completed는 생성 성공을 나타내며 data.data에 결과가 포함됩니다. 다른 상태에서는 data.data가 null입니다.

failed_reasonstring선택

status가 failed일 때만 반환되며 실패 이유를 설명합니다. completed와 processing에는 이 필드가 없습니다.

완료 · completed

다운로드 URL은 data.data.results에 있습니다.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "completed",
    "data": {
      "results": [
        "https://example.com/generated.png"
      ],
      "processing_time": 18
    }
  }
}

다른 상태

processing 또는 failed에서는 data.data가 null입니다. 아래는 failed 예시이며, failed일 때만 failed_reason이 포함됩니다. processing이면 조회를 계속하고, failed이면 중단하세요.

POST /api/v1/check · HTTP 200

{
  "data": {
    "id": "task_example",
    "created_at": 1791244800,
    "model": "gpt-image-2-5",
    "status": "failed",
    "data": null,
    "failed_reason": "Generation failed."
  }
}

크레딧 사용량

한 번의 요청으로 이미지 한 장을 생성할 때 소비되는 크레딧입니다.

한 번의 요청으로 이미지 한 장을 생성할 때 소비되는 크레딧입니다.
해상도	1K	2K	4K
이미지 한 장	12	36	50

선택 매개변수 생략: 5 크레딧

해당 요금을 적용하려면 표에 나열된 input 매개변수를 명시적으로 설정하세요. 여러 이미지를 생성하는 요청은 더 많은 크레딧을 소비할 수 있습니다.

POST /api/v1/create 응답의 credits 필드는 해당 작업에 실제로 차감된 크레딧을 나타냅니다.