GPT Image 2.5 API로 이미지를 생성하고 편집하는 방법

OpenAI Images API에서 GPT Image 2.5를 사용하려면 gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst를 선택하고 client.images.generate()나 client.images.edit()를 호출하면 됩니다. 응답의 data[0].b64_json을 디코딩하면 이미지 파일로 저장할 수 있습니다.

아래 예제는 2026년 9월 9일 확인한 OpenAI 이미지 생성 가이드를 기준으로 작성했습니다. 문서와 대조했으며 유료 추론 호출로 실행 검증한 예제는 아닙니다. OpenAI에 직접 요청하는 코드이므로 다른 게이트웨이를 쓰려면 해당 업체의 모델 ID, 엔드포인트 지원 여부, 요금을 별도로 확인해야 합니다.

먼저 모델을 선택하세요

이 구분은 선택의 출발점이며 개별 이미지의 결과를 보장하지 않습니다. Flare와 Sunburst 비교에서 판단 기준을 살펴보세요. API에는 제품군 이름이 아닌 정확한 모델 ID를 넣어야 합니다.

Python으로 이미지 생성하기

최신 SDK를 설치하고 OPENAI_API_KEY 환경 변수로 OpenAI API 키를 전달합니다. 키를 소스 파일에 직접 넣지 마세요.

python -m pip install --upgrade openai

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt=(
        "Create a clean product photograph of a ceramic tea cup on a "
        "warm gray background. Soft natural light, no text or watermark."
    ),
    size="1024x1024",
    quality="medium",
    output_format="png",
)

Path("tea-cup.png").write_bytes(
    base64.b64decode(result.data[0].b64_json)
)
print(result.usage)

PNG 출력을 요청하고 반환된 바이트를 PNG 파일로 저장하는 예제입니다. 비용을 비교할 때는 응답의 사용량 정보도 보관하세요. 이미지가 정상적으로 만들어졌다는 사실만으로는 토큰 소비량을 알 수 없습니다.

참조 이미지 편집하기

images.edit()에 입력 파일을 전달하고 바꿀 부분과 유지할 부분을 구분해서 적습니다. 다음 예제의 product.png는 로컬에 이미 있는 파일입니다.

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

with open("product.png", "rb") as reference:
    result = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=reference,
        prompt=(
            "Remove the background from this product photograph. "
            "Preserve the product shape, colors, and label text. "
            "Use a fully transparent background, with no checkerboard."
        ),
        size="1024x1024",
        quality="high",
        background="transparent",
        output_format="png",
    )

Path("product-cutout.png").write_bytes(
    base64.b64decode(result.data[0].b64_json)
)

결과를 원본 크기로 열어 라벨, 형태, 알파 투명도를 확인하세요. 보존하라는 지시가 항상 정확히 반영되는 것은 아닙니다. 이미지에 체크무늬가 그려져 있다면 실제 투명 배경이 아닙니다. OpenAI 프롬프트 가이드에는 부분 편집과 제품 형태 보존에 관한 예제가 더 있습니다.

크기와 품질을 명시적으로 설정하세요

두 모델 모두 auto, low, medium, high, xhigh, max를 지원합니다. 요청을 비교할 때는 품질을 직접 지정하는 편이 좋습니다. auto를 사용하면 조건을 일정하게 유지하기 어렵습니다.

권장 크기는 1024x1024, 1536x1024, 1024x1536입니다. 사용자 지정 크기는 다음 조건을 모두 만족해야 합니다.

• 가로와 세로는 각각 16의 배수여야 합니다.
• 어느 변도 3,840픽셀을 넘을 수 없습니다.
• 가로세로 비율은 1:3부터 3:1까지입니다.
• 전체 픽셀 수는 655,360~8,294,400이어야 합니다.

OpenAI는 2560x1440을 넘는 해상도를 실험적 지원으로 표시합니다. 4K 지원이라는 설명이 임의의 4K 크기나 동일한 안정성을 보장하지는 않습니다.

투명 배경에는 PNG 또는 WebP를 사용하세요. output_compression은 JPEG와 WebP에만 적용되며 PNG에는 적용되지 않습니다. 품질 설정을 높여도 모든 프롬프트에서 결과가 좋아지는 것은 아니므로 실제 입력으로 비교해야 합니다.

Responses API에서는 도구 안에 이미지 모델을 지정합니다

Images API는 이미지 모델을 직접 선택합니다. Responses API에서는 언어 모델과 이미지 생성 도구의 모델을 따로 지정합니다.

response = client.responses.create(
    model="gpt-6-astra",
    input="Generate a product photo of a ceramic tea cup on a gray background.",
    tools=[{
        "type": "image_generation",
        "model": "gpt-image-2.5-sunburst",
        "output_format": "png",
    }],
)

for index, item in enumerate(response.output):
    if item.type == "image_generation_call":
        Path(f"response-image-{index}.png").write_bytes(
            base64.b64decode(item.result)
        )

앞 예제의 import와 client를 사용합니다. OpenAI 문서에서도 최상위 모델과 도구 모델을 구분하는 이 방식을 안내합니다. Responses 요청에는 언어 모델의 토큰 비용도 포함될 수 있습니다. Images API와 비용을 비교하기 전에 요금 가이드를 확인하세요.

실제 서비스에 연결하기 전 확인할 점

사용할 계정과 제공업체에서 모델에 접근할 수 있는지 확인하세요. SDK를 업데이트한다고 계정 권한이 생기는 것은 아니며 OpenAI 예제만으로 다른 업체의 지원 여부를 판단할 수도 없습니다.

모델, 프롬프트, 품질, 크기, 반환 사용량, 응답 시간, 출력 파일을 기록하세요. 편집 작업에는 문구 정확도와 의도하지 않은 변경 여부도 포함해야 합니다. 기존 GPT Image 2를 대체한다면 전체 트래픽을 옮기기 전에 마이그레이션 체크리스트를 적용하세요.