APIMart를 통해 GPT-Image-2.5로 이미지 생성 및 편집

image2.5 APIMart 게이트웨이의 기능

image2.5 게이트웨이는 APIMart API를 통해 GPT Image 2.5 생성 및 편집 제품군에 액세스할 수 있도록 합니다. 각 이미지 모델마다 별도의 인증 정보와 요청 형식을 통합하는 대신, 하나의 기본 URL, 하나의 bearer 토큰, OpenAI 스타일의 /v1/images/generations 엔드포인트를 사용합니다.

API는 비동기 방식으로 작동합니다. 이미지 생성 요청은 인라인 이미지 대신 작업 ID를 반환합니다. 그러면 애플리케이션은 처리가 완료되거나 실패할 때까지 작업 엔드포인트를 폴링합니다. 성공한 작업에는 만료되기 전에 다운로드해야 하는 임시 출력 URL이 포함됩니다.

이 저장소에서 문서화하는 서비스는 APIMart입니다. gpt-image-2.5-ext 엔드포인트는 타사 릴레이 경로이며, gpt-image-2.5-flare와 gpt-image-2.5-sunburst는 토큰 과금 경로입니다. 프로덕션 실행 전에 현재 한도와 가격을 확인하세요.

주요 기능

• 하나의 API 기본 URL: 요청에는 https://api.apimart.ai/v1을 사용합니다.
• 두 가지 모델 변형: 일상적인 생성과 일괄 초안에는 Flare를, 정밀한 편집과 프로덕션용 에셋에는 Sunburst를 선택합니다.
• 두 가지 과금 방식: 릴레이 경로는 제공된 이미지 단위로 과금되며, 공식 경로는 토큰 기반 과금을 사용합니다.
• 비동기 처리: 요청을 제출하고 GET /v1/tasks/{task_id}를 폴링하여 진행 상황을 확인합니다.
• 다양한 출력 등급: 릴레이 경로는 1K, 2K, 4K를 지원합니다.
• 유연한 구도: 10가지 화면 비율 중에서 선택하거나 auto를 사용할 수 있습니다.
• 참조 기반 생성: 이미지 간 변환 또는 편집 작업을 위해 image_urls에 최대 16개의 항목을 제공할 수 있습니다.
• 소규모 배치: 릴레이 경로에서 n을 사용해 1~4개의 이미지를 요청할 수 있습니다.

올바른 모델 경로 선택

이미지당 과금 릴레이 경로

제공된 이미지당 고정 과금을 원한다면 model: "gpt-image-2.5-ext"를 사용합니다. version: "flare" 또는 version: "sunburst"로 기반 변형을 선택합니다.

• flare는 대량 생성, 일상적인 이미지, 초안 제작에 적합합니다.
• sunburst는 편집 및 참조 기반 프로덕션 작업에 적합합니다.

저장소에서는 2026년 9월 16일 두 변형 모두에 대해 제공된 1K 이미지당 $0.0085의 가격을 확인했습니다. 또한 2K는 $0.014, 4K Flare는 $0.021로 기록했으며, 4K Sunburst는 실시간 가격을 확인할 것을 안내했습니다. 이는 관찰 시점의 가격이며 영구적으로 보장되는 값이 아닙니다.

공식 토큰 과금 경로

토큰 기반 과금을 사용하려면 gpt-image-2.5-flare 또는 gpt-image-2.5-sunburst를 직접 사용합니다. 이러한 경로에서는 version 필드를 생략하며 low, medium, high, xhigh, max 품질 단계를 지원합니다. 공식 경로는 정확한 픽셀 크기도 지원합니다.

실용적인 기준으로는 이미지당 비용을 예측할 수 있어야 할 때 릴레이 경로를 사용하고, 품질 제어 또는 정확한 크기가 필요할 때 공식 경로를 고려하면 됩니다.

출력 예시 범위

저장소에는 제품 사진, 인물 사진, 건축, UI 에셋, 일러스트, 게임 아트, 음식 사진, 매크로 이미지용 프롬프트 예시가 포함되어 있습니다. 다음 이미지는 프로젝트에 포함된 시각적 출력 유형을 보여 줍니다.

설치 및 설정

1. API 키 생성

APIMart API 키 페이지에서 키를 발급받습니다. 소스 코드에 직접 입력하지 말고 환경 변수에 저장하세요.

export APIMART_API_KEY="your-api-key"

2. 클라이언트 선택

cURL은 표준 명령줄 설치 외에 프로젝트 종속성이 필요하지 않습니다. Python 예제를 사용하려면 requests 패키지를 설치하세요.

python -m pip install requests

저장소에는 Node.js 18 이상에서 사용할 수 있는 JavaScript 예제도 포함되어 있으며, 이 환경에서는 fetch를 전역으로 사용할 수 있습니다.

3. 요청 헤더 이해

Authorization 헤더에 API 키를 전송합니다. 릴레이 경로 예제에서는 응답 버전 헤더와 고유한 멱등성 키도 사용합니다.

• Authorization: Bearer $APIMART_API_KEY
• Content-Type: application/json
• X-APIMart-Response-Version: 2026-07-27
• Idempotency-Key: unique-request-value

동일한 제출을 재시도할 때는 같은 멱등성 키를 재사용합니다. 의도적으로 새 이미지 작업을 생성하려면 새 키를 만드세요.

기본 사용법: 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을 사용하세요.

작업 폴링

반환된 작업 ID로 task_01EXAMPLE을 바꾸세요.

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01EXAMPLE \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

작업 상태는 pending과 processing을 거쳐 completed 또는 failed에 도달합니다. 응답에는 progress, cost, credits_cost도 포함될 수 있습니다. 완료되면 result.images[].url에서 이미지 URL을 가져오고 expires_at을 확인하세요.

엔드투엔드 Python 예제

이 예제는 이미지 한 장을 제출하고 작업이 최종 상태에 도달할 때까지 5초마다 상태를 확인합니다.

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_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,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_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(
    "A sky garden at dawn, architectural photography",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

프로덕션 클라이언트에서는 URL만 반환하지 말고 전체 작업 객체를 반환하거나 저장하세요. 그러면 비용, 진행률, 만료 및 오류 정보를 보존할 수 있습니다.

편집에 참조 이미지 사용

릴레이된 경로에서 이미지 간 생성 또는 편집을 수행하려면 image_urls 배열을 추가하세요. 이 배열에는 최대 16개의 URL 또는 데이터 URL을 포함할 수 있습니다. 저장소에 따르면 이 경로에서는 참조 이미지에 별도 요금이 부과되지 않습니다.

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Preserve the product label, replace the background with soft off-white, and add a natural cast shadow",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

저장소에서는 편집 정밀도와 참조 기반 작업에 Sunburst를 권장 변형으로 제시합니다. 접근 가능한 URL 또는 유효한 데이터 URL을 사용하고, 목록을 문서에 명시된 제한 내로 유지하세요.

릴레이된 경로의 요청 필드 참조

• model: 필수입니다. gpt-image-2.5-ext로 설정하세요.
• version: flare 또는 sunburst를 허용하며, 기본값은 Flare입니다.
• prompt: 필수이며 trim 후 비어 있으면 안 됩니다.
• 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을 포함할 수 있습니다.

토큰 과금 경로 호출

공식 경로는 동일한 생성 경로를 사용하지만 모델 ID를 변경하고 version을 제거하며 품질 설정을 추가합니다. 다음 예제에서는 고품질의 Sunburst를 선택합니다.

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
  }'

현재 필드 정의는 공식 경로 레퍼런스와 릴레이 경로 레퍼런스를 참조하세요.

안정적인 통합을 위한 고급 팁

1. 재시도를 멱등적으로 처리하세요. 제출 시간이 초과되어 작업이 생성되었는지 확실하지 않은 경우, 원래의 멱등성 키를 유지하세요. 새 키를 사용하면 요금이 부과되는 생성 작업이 중복으로 생성될 수 있습니다.
2. 폴링을 일반적인 워크플로로 처리하세요. completed와 failed를 모두 처리하세요. 지나치게 빠르게 폴링하지 마세요. 저장소 예제에서는 확인 사이에 5초를 기다립니다.
3. 응답으로 반환된 폴링 URL을 사용하세요. 응답에는 data.poll_url이 포함되어 있어 작업 엔드포인트를 수동으로 재구성할 필요가 없습니다.
4. 출력을 신속하게 다운로드하세요. 생성된 이미지 URL은 임시 URL입니다. expires_at 시간 전에 각 출력을 자체 저장소로 복사하세요.
5. 실제 비용을 기록하세요. 작업 응답의 cost와 credits_cost를 저장하세요. 이를 통해 실제 청구액과 공개된 가격을 비교할 수 있습니다.
6. 유료 요청 하나로 비용을 검증하세요. 가격과 프로모션 라우팅은 변경될 수 있으므로, 대규모 배치를 시작하기 전에 소규모 테스트를 실행하세요.
7. 적절한 경로를 사용하세요. 이미지당 예측 가능한 과금과 최대 4개 이미지의 배치가 필요하면 릴레이 경로를 선택하세요. 품질 단계나 정확한 픽셀 제어가 중요하면 공식 모델 ID를 선택하세요.
8. 클라이언트를 다시 작성하지 않고 변형을 전환하세요. 릴레이 경로에서는 version만 flare와 sunburst 사이에서 변경하면 됩니다.
9. 자격 증명을 보호하세요. API 키는 환경 변수나 시크릿 관리자에 보관하고 브라우저 측 코드에 절대 노출하지 마세요.

결론

APIMart의 image2.5 게이트웨이는 GPT Image 2.5 생성 및 편집에 일관된 방식으로 액세스할 수 있도록 합니다. 예측 가능하고 대량의 생성 작업에는 gpt-image-2.5-ext와 Flare로 시작하고, 편집 또는 참조 기반 작업에는 Sunburst로 전환하세요. 토큰 기반 과금과 확장된 품질 제어가 작업에 더 적합하다면 공식 모델 ID를 사용하세요.

핵심 통합 패턴은 간단합니다. 이미지 요청을 제출하고, 반환된 작업 ID를 저장한 다음, 완료될 때까지 폴링하고, 보고된 비용을 확인한 뒤, 임시 URL이 만료되기 전에 모든 결과를 다운로드하세요. 규모를 확장하기 전에 현재 APIMart 가격을 확인하고 소규모 유료 요청으로 선택한 경로를 검증하세요.