이 프로젝트가 제공하는 것
image2.5 프롬프트 갤러리는 GPT Image 2.5를 통해 실행하고 결과 이미지와 함께 게시한 12개의 프롬프트를 실용적으로 모아 둔 컬렉션입니다. 각 레시피에는 프롬프트, 모델 버전, 화면 비율, 출력 결과가 기록되어 있어, 자체 애플리케이션에 맞게 조정하기 전에 프롬프트를 평가하기가 더 쉽습니다.
예제에서는 https://api.apimart.ai/v1의 APIMart OpenAI 호환 엔드포인트를 사용합니다. 릴레이 경로는 비동기 방식입니다. 애플리케이션이 이미지 요청을 제출하면 작업 ID를 받고, 작업 엔드포인트를 폴링한 뒤 처리가 완료되면 이미지를 다운로드합니다.
주요 기능
- OpenAI 호환 생성 경로: 요청은
POST /v1/images/generations로 전송됩니다. - 두 가지 릴레이 변형: 일반적인 생성을 위해
version: "flare"를 사용하거나, 편집 및 참조 기반 작업을 위해version: "sunburst"를 사용합니다. - 다양한 출력 등급:
1K,2K,4K중에서 선택할 수 있습니다. - 유연한 프레이밍:
auto또는 지원되는 10가지 화면 비율 중 하나를 사용합니다. 여기에는1:1,16:9,9:16,4:3이 포함됩니다. - 일괄 출력:
n을 사용해 이미지 1~4장을 요청할 수 있습니다. - 참조 이미지 지원:
image_urls에 최대 16개의 URL 또는 데이터 URL을 제공할 수 있습니다. - 호출별 비용 보고: 완료된 작업 데이터에는
cost와credits_cost가 포함됩니다. - 멱등성 재시도: API는
Idempotency-Key헤더를 지원하므로 동일한 제출을 재시도할 때 중복 작업을 방지할 수 있습니다.
올바른 모델 경로 선택
APIMart는 릴레이 방식과 공식 GPT Image 2.5 경로를 모두 제공합니다. 요청 필드와 과금 방식이 다르므로 통합을 작성하기 전에 경로를 선택해야 합니다.
릴레이 이미지당 과금 경로
model을 gpt-image-2.5-ext로 설정하고 version: "flare" 또는 version: "sunburst"를 포함합니다. 갤러리 예제에서 사용하는 경로이며, 전달된 이미지당 과금됩니다.
flare: 일반적인 생성 및 일괄 초안에 적합합니다.sunburst: 정밀한 편집과 참조 이미지, 객체, 로고 또는 제품 라벨을 보존해야 하는 작업에 적합합니다.
공식 토큰 과금 경로
gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst를 직접 사용합니다. 이러한 모델 ID와 함께 version 필드를 보내지 마세요. 공식 경로는 토큰 기준으로 과금되며 low부터 max까지의 품질 단계와 정확한 픽셀 크기를 지원합니다.
경로 형식을 섞지 마세요.
gpt-image-2.5-ext별칭에는 버전 선택자가 필요하지만, 공식 모델 ID에는 버전 선택자를 포함하면 안 됩니다.
설치 및 설정
1. 계정 생성 및 충전
APIMart 키 페이지에서 API 키를 발급받습니다. 저장소에 따르면 이 서비스에는 무료 할당량이 없으며 $1부터 충전할 수 있습니다.
2. 환경 변수에 키 저장
export APIMART_API_KEY="your-api-key"키를 애플리케이션 소스 코드에 직접 넣거나 버전 관리 시스템에 커밋하지 마세요.
3. Python 의존성 설치
Python 예제에서는 타사 requests 패키지를 사용합니다.
python -m pip install requestscurl을 선호한다면 셸에서 curl과 uuidgen 같은 UUID 생성기를 사용할 수 있는지 확인하세요.
curl로 첫 이미지 요청 만들기
다음 요청은 릴레이 flare 변형을 사용해 정사각형 1K 이미지를 생성합니다.
IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header "Authorization: Bearer $APIMART_API_KEY" \
--header "Content-Type: application/json" \
--header "X-APIMart-Response-Version: 2026-07-27" \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data '{
"model": "gpt-image-2.5-ext",
"version": "flare",
"prompt": "A cozy reading nook beside a window on a rainy day, warm table lamp, cinematic lighting",
"size": "1:1",
"resolution": "1K",
"n": 1
}'제출이 성공하면 HTTP 202가 반환됩니다. data.id에서 작업 식별자를 읽거나 반환된 data.poll_url을 사용하세요.
작업 폴링
curl --request GET \
--url "https://api.apimart.ai/v1/tasks/TASK_ID" \
--header "Authorization: Bearer $APIMART_API_KEY" \
--header "X-APIMart-Response-Version: 2026-07-27"작업은 일반적으로 pending에서 processing으로 이동한 다음 completed 또는 failed로 종료됩니다. 완료되면 result.images[].url에서 생성된 URL을 가져옵니다.
생성된 이미지 URL에는
expires_at타임스탬프가 포함됩니다. URL이 만료되기 전에 각 파일을 다운로드하고 저장하세요.
엔드투엔드 Python 클라이언트 구축
이 예제는 요청 하나를 제출하고, HTTP 오류를 확인하며, 5초마다 폴링한 뒤 완료된 작업 레코드를 반환합니다. 새로운 생성마다 새로운 멱등성 키를 만듭니다.
import os
import time
import uuid
import requests
BASE_URL = "https://api.apimart.ai/v1"
API_KEY = os.environ["APIMART_API_KEY"]
COMMON_HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-APIMart-Response-Version": "2026-07-27",
}
def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
submit_headers = {
**COMMON_HEADERS,
"Idempotency-Key": str(uuid.uuid4()),
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers=submit_headers,
timeout=60,
json={
"model": "gpt-image-2.5-ext",
"version": version,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
},
)
response.raise_for_status()
task_id = response.json()["data"]["id"]
while True:
poll_response = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=COMMON_HEADERS,
timeout=60,
)
poll_response.raise_for_status()
task = poll_response.json()["data"]
if task["status"] == "completed":
return task
if task["status"] == "failed":
raise RuntimeError(f"Generation failed: {task}")
time.sleep(5)
result = generate_image(
"Studio product hero of a matte ceramic espresso cup on a warm stone pedestal, soft window light, 85mm lens look, minimal beige backdrop, crisp shadow"
)
print("Cost:", result.get("cost"))
for image in result["result"]["images"]:
print("Image URL:", image["url"])
print("Expires at:", image.get("expires_at"))안전하게 재시도하기
제출 시간이 초과되거나 재시도 가능한 응답을 받으면 동일한 Idempotency-Key를 사용해 같은 논리적 요청을 다시 보내세요. 새 이미지를 의도적으로 생성할 때는 새 키를 사용하세요. 소스 또는 참조가 변경되어 완료된 작업을 다시 생성해야 하는 경우에도 새 키를 사용하세요.
주요 요청 필드 이해하기
model: 필수 항목입니다. 중계 경로에는gpt-image-2.5-ext를 사용하세요.version:flare또는sunburst이며, 기본값은flare입니다.prompt: 필수 항목이며 공백만 포함할 수 없습니다.resolution:1K,2K또는4K이며, 기본값은1K입니다.size: 기본값은auto입니다. 지원되는 비율은1:1,16:9,9:16,4:3,3:4,3:2,2:3,5:4,4:5,21:9입니다.n: 이미지 개수이며, 중계 경로에서는 1개부터 4개까지 지정할 수 있습니다.image_urls: 최대 16개의 이미지 URL 또는 데이터 URL을 포함할 수 있는 선택적 배열입니다.
더 안정적인 프롬프트 작성하기
갤러리는 프롬프트를 모호한 형용사 목록이 아니라 간결한 제작 브리프로 취급합니다. 유용한 구조는 주제, 재질, 조명, 구도 또는 렌즈, 마감 표현으로 구성됩니다.
- 주제를 명확히 지정하세요: 주요 사물, 인물, 장면 또는 환경을 식별하세요.
- 물리적 재질을 구체화하세요:
matte ceramic,frosted glass,clay render와 같은 표현을 사용하세요. - 조명을 설정하세요: 부드러운 창가 조명, 자연스러운 측면 조명, 하이키 스튜디오 조명 또는 극적인 역광을 설명하세요.
- 구도를 고정하세요: 중앙 배치, 오버헤드 플랫 레이, 와이드 시네마틱 구도 또는 원하는 다른 레이아웃을 명시하세요.
- 렌즈 표현을 추가하세요:
85mm,24mm,macro,focus stacked와 같은 용어로 원근과 디테일을 유도할 수 있습니다. - 마감 표현을 선택하세요: 회화적 디테일, 상업 제품 사진, 선명한 벡터 가장자리와 같은 표현으로 시각적 처리 방식을 제어할 수 있습니다.
예:
Cosmetics packshot of a frosted glass bottle with amber serum,
water droplets on the surface, seamless pale pink backdrop,
high detail commercial product photography
참조 이미지 사용하기
이미지 간 변환 또는 참조 기반 작업을 수행하려면 중계 요청에 image_urls 배열을 추가하세요. 이 경로는 최대 16개의 참조 이미지를 지원합니다.
{
"model": "gpt-image-2.5-ext",
"version": "sunburst",
"prompt": "Preserve the product and label, replace the background with soft off-white, and add a natural cast shadow",
"image_urls": [
"https://example.com/product-reference.jpg"
],
"size": "1:1",
"resolution": "2K",
"n": 1
}안정적으로 접근할 수 있는 참조 URL을 사용하세요. 참조 URL이 만료되어 작업이 실패하면 이미지를 다시 호스팅하고 새 멱등성 키로 새 작업을 제출하세요.
공식 경로 호출하기
공식 경로는 중계 경로의 version 선택기 대신 직접 모델 ID와 quality 설정을 사용합니다.
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header "Authorization: Bearer $APIMART_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-image-2.5-sunburst",
"prompt": "Preserve the product label, replace the background with soft off-white, add a natural cast shadow",
"size": "1:1",
"resolution": "1k",
"quality": "high",
"n": 1
}'현재 필드 세부 정보는 공식 경로 문서와 중계 경로 문서를 참조하세요.
고급 프로덕션 팁
제출과 처리를 분리하세요
웹 요청을 계속 열어 두는 대신 반환된 작업 ID를 큐나 데이터베이스에 저장하세요. 백그라운드 작업자가 완료되지 않은 작업을 폴링하고 완료된 결과를 저장할 수 있습니다.
적절한 폴링 간격을 사용하세요
저장소 예제에서는 5초마다 폴링합니다. 불필요한 트래픽을 만드는 지나치게 짧은 반복을 피하세요. 대규모 작업에서는 작업이 대기 중이거나 처리 중일 때 백오프를 추가하세요.
실제 비용을 기록하세요
완료된 모든 작업에서 cost 또는 credits_cost를 저장하세요. 이렇게 하면 추정치에만 의존하지 않고 호출별 지출 기록을 확보할 수 있습니다.
README에는 중계 경로의 관찰 가격이 제공된 1K 이미지당 $0.0085, 2K 이미지당 $0.014, 4K flare 이미지당 $0.021이라고 나와 있습니다. 4K sunburst 가격은 표에 확정되어 있지 않았습니다. 이 수치는 2026년 9월에 관찰된 가격이므로 예산을 책정하거나 규모를 확장하기 전에 실시간 가격을 확인하세요.
결과를 즉시 다운로드하세요
result.images[].url을 영구 저장소로 간주하지 마세요. expires_at 이전에 파일을 다운로드한 다음 애플리케이션이 관리하는 저장소로 옮기세요.
확장 전에 작게 시작하세요
n: 1과 함께 1K에서 프롬프트를 검증하세요. 주제, 구성, 스타일이 안정된 후에만 해상도를 높이거나 여러 출력을 요청하세요.
대상에 맞게 종횡비를 선택하세요
- 아이콘, 제품 카드, 정사각형 소셜 콘텐츠에는
1:1 - 영화 같은 장면, 대시보드, 프레젠테이션 헤더에는
16:9 - 세로형 모바일 및 소셜 레이아웃에는
9:16 - 에디토리얼 일러스트와 음식 사진에는
4:3 - 인물 사진과 패션 구성에는
3:4
문제 해결
401또는 잘못된 API 키: 키를 다시 복사하고 공백이나 줄바꿈 문자가 포함되어 있지 않은지 확인하세요. 헤더는Authorization: Bearer $APIMART_API_KEY형식이어야 합니다.- 잔액 또는 크레딧 오류: 계정에 금액을 충전하세요. 저장소에는 무료 대체 할당량이 없다고 명시되어 있습니다.
429응답: 동시성을 낮추고 백오프한 후 동일한 멱등성 키로 같은 제출을 재시도하세요.400또는 모델을 찾을 수 없음:gpt-image-2.5-ext에 버전이 포함되어 있고 공식 직접 모델 ID에는 버전이 포함되지 않는지 확인하세요.- 작업 상태가
failed임: 프롬프트가 거부되었거나 참조 URL이 만료되었는지 확인하세요. 입력을 수정하고 새 키로 새 작업을 제출하세요. - 출력 URL이 더 이상 작동하지 않음: 임시 URL이 만료되었을 가능성이 높습니다. 이후 완료되는 출력은 즉시 다운로드해야 합니다.
결론
image2.5 Prompt Gallery는 GPT Image 2.5로 에셋을 생성하는 반복 가능한 워크플로를 보여 줍니다. 올바른 경로를 선택하고, 프로덕션 스타일의 프롬프트를 작성하고, 비동기 요청을 제출하고, 작업 ID를 폴링하고, 보고된 비용을 기록한 다음, 만료 전에 결과를 다운로드하는 과정입니다. 단일 1K 이미지로 시작해 품질과 요금을 확인한 후 더 높은 해상도, 배치 또는 참조 기반 sunburst 워크플로로 확장하세요.