GPT 이미지 2.5 API 가이드: Sunburst와 Flare를 사용한 이미지 생성 및 편집

Image API를 사용하여 직접적인 단일 단계 생성 및 편집을 수행합니다. 이미지 생성이 대화 또는 다단계 프로세스에 속할 경우 Responses API를 사용하세요. Image API에서 직접 gpt-image-2.5-sunburst 또는 gpt-image-2.5-flare를 선택하십시오.

먼저 인터페이스를 선택하세요

이미지 API는 생성 및 편집 엔드포인트를 제공합니다. 응답 API는 도구로서의 반복적 이미지 생성을 지원하며, 이미지 입력과 출력을 컨텍스트 내에 유지할 수 있습니다. 이러한 아키텍처 결정은 SDK 문법보다 더 중요합니다.

최소 생성 모드

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "깔끔한 디자인 일러스트레이션, 태양광 도서관을 묘사하며, 텍스트 요소 없음"
  size: "1536x1024",
  quality: "중간",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

API 키를 서버 측에 저장하고 소스 코드 제어에서 멀리 두십시오.

출력 제어

두 모델 모두 자동부터 최고 품질까지, 공식 제한 내의 사용자 정의 크기, PNG/JPEG/WebP 형식, JPEG/WebP 압축, 그리고 투명 또는 불투명 배경을 지원합니다. 알파 채널이 필요하면 PNG 또는 WebP 형식을 사용하세요.

편집 모드

하나 이상의 이미지를 사용하여 편집 엔드포인트를 호출하고, 변경 사항과 유지할 세부 사항을 분리하는 프롬프트를 제공합니다. 전송 전에 입력 유형과 크기를 확인합니다. 각 참조에 역할을 할당합니다.

생산 검증

저장 요청 ID, 모델 또는 스냅샷, 프롬프트 버전, 크기, 품질, 출력 형식, 참조 정보, 지연 시간 및 수락 결과. 일시적 오류만 재시도하십시오. 요청을 변경하지 않고 의미 오류가 있는 출력을 자동으로 재시도하지 마십시오.

모델 라우팅

일상적인 작업은 Flare로, 고정밀 작업은 Sunburst로 라우팅하세요. 고정된 기준을 사용하여 더 빠른 모델이 더 저렴하다고 가정하지 마세요. 현재 토큰 요금이 일치하기 때문입니다.

오류 처리

인증 처리, 조직 검증, 속도 제한, 잘못된 크기, 콘텐츠 심사 및 빈 출력을 처리합니다. 조건에 맞는 일시적 오류에는 지터가 포함된 지수 백오프 전략을 사용하고 재시도 횟수를 제한합니다. 불필요하게 개인 이미지 데이터를 기록하지 마십시오.

다운스트림 애니메이션

이미지를 디코딩하고 승인한 후, 출처 정보를 저장하고 자산을 다운스트림 워크플로우로 전달합니다. 정적 이미지를 캐릭터 중심의 스토리보드, 비디오 또는 편집 애니메이션으로 변환해야 할 때 Elser AI가 관련됩니다. 실시간 제품에서 지원되는 업로드 및 모델 옵션을 확인하세요.

생성 엔드포인트와 편집 엔드포인트

텍스트로 새 이미지를 생성할 때는 생성 기능을 사용합니다. 하나 이상의 기존 이미지가 주체나 초기 상태를 정의하는 경우 편집 기능을 사용합니다. 다중 참조 편집의 경우 안정적인 순서로 입력을 전송하고 프롬프트에서 해당 순서를 식별하십시오. 요청 전에 파일 유형과 크기를 확인하여 잘못된 입력이 로컬에서 실패하도록 하십시오.

반복 작업을 위한 응답 API

사용자가 이미지를 생성하고, 대화 방식으로 이미지를 평가하며 후속 변경을 요청할 때 Responses API가 매우 유용합니다. 이미지 생성 도구는 더 큰 응답 흐름에 참여할 수 있으며, 이미지 파일 ID는 컨텍스트에 보존될 수 있습니다. 이는 애플리케이션 측의 조합 작업을 줄여주지만, 제품에는 여전히 명확한 상태와 버전 관리가 필요합니다. "이전과 동일"은 핵심 제약 조건으로 충분하지 않습니다. 다시 표현해 주십시오.

더 안전한 애플리케이션 아키텍처

클라이언트, 작업 큐, 자산 저장소 및 메타데이터 저장소를 서로 독립적으로 유지합니다. 클라이언트는 간단한 설명을 제출합니다. 서버는 해당 설명을 검증하고 작업을 생성합니다. 작업 프로세스는 OpenAI를 호출하고 결과를 디코딩하여 생성된 자산 ID 아래에 저장합니다. 메타데이터는 모델 스냅샷, 프롬프트, 설정, 참조 및 검토 결과를 기록합니다. 클라이언트는 원본 자격 증명이 아닌 단기 유효 자산 URL을 받습니다.

장시간 실행되는 호출은 취약한 브라우저 요청을 점유해서는 안 됩니다. 복잡한 프롬프트는 많은 시간이 소요될 수 있으므로, 처리 중, 완료, 실패 상태를 표시해야 합니다. 작업 제출을 멱등성(idempotent) 있게 만들어 클라이언트 재시도 시 중복 비용이 발생하지 않도록 하십시오.

검증 규칙

지정된 사용자 정의 크기가 문서에 명시된 16의 배수, 여백, 비율 및 총 픽셀 제한 조건을 충족하는지 확인합니다. 배경이 투명한 경우 PNG 또는 WebP 형식을 사용해야 합니다. 압축 값을 지원 범위 내로 제한합니다. 알려진 품질 및 모델 매개변수만 허용합니다. API 호출 전에 프롬프트가 누락된 경우 거부합니다.

신뢰성과 관측 가능성

요청 ID, HTTP 상태, 오류 범주, 시도 횟수 및 지연 시간을 기록하고, 개인 이미지나 기밀 정보는 기록하지 않습니다. 지터가 포함된 지수 백오프 재시도 속도 제한 및 조건에 맞는 서버 오류를 사용합니다. 인증, 잘못된 매개변수 또는 정책 오류는 그대로 재시도하지 않습니다. 시도 횟수에 상한을 설정하고 유용한 제품 메시지를 반환합니다.

모니터:

성공률 및 이미지 수락률.
모델 및 품질별 p50 및 p95 지연 시간.
입력 및 출력 토큰.
재시도 및 반복 작업.
심사 결과.
저장 및 전송 실패.

안전과 권리

API 키를 서버 측 키 관리자에 저장하세요. 원본 이미지와 생성된 이미지에 대한 접근 제어를 시행하세요. 보존 규칙을 설정하고, 노출되어서는 안 되는 메타데이터를 제거하며, 사용자가 업로드한 자료에 대한 권리를 기록하세요. OpenAI는 GPT 이미지 모델에 접근하려면 조직 인증이 필요할 수 있다고 밝혔습니다. 이를 런타임 예외가 아닌 온보딩 전제 조건으로 처리하세요.

스냅샷 정책

날짜가 없는 ID를 사용하여 지속적인 모델 업데이트를 받으세요. 재현성이 더 중요할 때는 날짜가 있는 스냅샷을 고정하세요. 프로덕션 트래픽을 변경하기 전에 동일한 기준을 사용하여 새 스냅샷을 평가하세요. 각 자산이 반환하거나 구성한 실제 모델 식별자를 저장하세요.

시작 문서에 코드가 포함된 경우, 그 옆에 날짜가 포함된 검증 날짜를 표시하십시오. 독자는 모델의 가용성, SDK 구문, 속도 제한 및 조직 요구 사항이 문서의 개념적 구조와 독립적으로 변경될 수 있음을 이해해야 합니다.

타입화된 요청 계약

이미지 모델 자체가 구조화된 출력을 제공하지 않더라도 내부 스키마를 정의하세요. 하나의 작업에는 prompt(프롬프트), workflow(워크플로우), model(모델), quality(품질), width(너비), height(높이), format(형식), background(배경), compression(압축), 참조 리소스 ID 및 멱등성 키가 포함될 수 있습니다. SDK 호출로 변환하기 전에 이를 검증하세요.

브라우저에서 임의의 모델 이름이나 파일 경로를 노출하지 마십시오. 클라이언트에 표시되는 소수의 옵션을 서버가 승인한 값에 매핑해야 합니다. 접근 제어된 자산 ID로 참조를 해석하고 현재 사용자가 해당 자산을 읽을 권한이 있는지 확인하십시오.

편집 요청 스케치

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [fs.createReadStream("approved-character.png")],
  prompt: `외투만 짙은 녹색 양모로 바꿔 주세요.
얼굴, 머리카락, 눈 색깔, 자세, 손, 구도 및 배경을 유지합니다.
텍스트, 보석 또는 다른 사람을 추가하지 마십시오.`
  size: "1024x1536",
  quality: "고품질",
  output_format: "png"
});

const bytes = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("character-green-coat.png", bytes);

정확한 SDK 인터페이스는 변경될 수 있으므로, 배포 전에 현재 공식 가이드를 참조하여 예제를 확인하시기 바랍니다. 프로덕션 코드는 스트리밍 또는 버퍼링을 적절히 처리하고, 응답 존재 여부를 검증하며, 원자적으로 저장해야 하며, 모든 호출이 유효한 데이터를 반환한다고 가정해서는 안 됩니다.

멱등성과 중복 비용

사용자가 더블 클릭하거나 네트워크 재시도로 인해 동일한 비용이 많이 드는 생성 작업이 두 번 제출될 수 있습니다. 작업 생성 시 멱등 키를 할당하고, 배포 전에 작업을 지속화하며, 동일한 키가 다시 나타나면 기존 작업을 반환합니다. 작업 프로세스는 작업을 한 번만 가져와 최종 상태를 기록해야 합니다.

여러 변형을 생성하려는 경우, 이를 명확한 제품 작업으로 표현해야 하며, 우발적인 재시도가 아니어야 합니다. 이미지 API는 문서에서 n 매개변수를 통해 여러 이미지를 생성하는 것을 지원하지만, 비용 및 검토 모델은 각 출력을 통계적으로 처리해야 합니다.

심사 및 실패 사용자 경험

모든 프롬프트와 이미지는 보안 필터를 거쳐야 합니다. 민감한 내부 심사 세부 사항을 노출하지 않으면서도 사용자가 합법적인 요청을 수정할 수 있도록 충분한 지침을 제공해야 합니다. 정책 거부를 잘못된 설정, 권한 부족, 속도 제한 및 일시적인 서비스 장애와 구분하십시오.

Sunburst를 사용할 수 없을 때, 다른 모델로 조용히 대체하지 마십시오. 이는 품질 또는 계약 조건을 위반할 수 있습니다. 명확한 상태를 반환하거나, 제품이 해당 동작을 공개하고 기록한 경우에만 대체 방안을 사용해야 합니다.

자산 저장 및 전달

메모리에서 base64를 디코딩하고 크기 제한을 설정하며, 선언된 형식을 확인하고, 체크섬을 생성하여 변경 불가능한 원본 파일을 저장합니다. 별도로 썸네일을 생성합니다. 단기 유효한 서명 URL과 적절한 콘텐츠 유형을 통해 서비스를 제공합니다. 투명 PNG/WebP의 알파 채널을 유지하여 손실 변환이 전달 파일을 손상시키지 않도록 합니다.

적절한 접근 제어를 통해 힌트와 참고 자료를 민감도에 맞게 저장하세요. 보존 및 삭제 동작을 정의하세요. 출처가 없는 생성 파일은 감사, 재현 또는 Elser 애니메이션 프로젝트에 안전하게 전달하기 어렵습니다.

출시 전 체크리스트

계정 및 조직 액세스 권한이 확인되었습니다.
API 키는 서버 측에서 관리되며 교체 가능합니다.
모델 ID 및 차원 규칙이 화이트리스트에 등록되었습니다.
과제 제출은 멱등적입니다.
재시도 횟수는 제한적이며 분류됩니다.
사용 현황, 지연 시간 및 수용도가 모니터링됩니다.
이미지와 메타데이터에는 보존 규칙이 있습니다.
신분, 브랜드 및 텍스트 민감 출력에 대해 인공 심사가 존재합니다.
날짜가 기록된 스냅샷 정책과 롤백 경로가 저장되었습니다.

자주 묻는 질문

어떤 API를 선택해야 하나요?

Image API는 직접 생성/편집에 사용되며, Responses API는 대화형 또는 다단계 이미지 경험에 사용됩니다.

여러 장의 이미지를 요청할 수 있나요?

Image API는 문서에서 여러 출력을 위한 n 매개변수를 지원합니다.

API가 URL을 반환하나요?

현재 가이드는 이미지 API의 base64 인코딩 이미지 데이터를 보여줍니다. 디코딩하여 안전하게 저장하세요.

결론

신뢰할 수 있는 통합은 명확한 모델 라우팅과 엄격한 검증, 관찰 가능성 및 자산 검토를 결합합니다. 핵심 이미지 경로가 신뢰할 수 있을 때만 최소한의 직접 요청을 먼저 구축한 후, 대화 상태나 다운스트림 애니메이션을 추가하십시오.