GPT Image 2.6 Sunburst

텍스트와 최대 16장의 참조 이미지로 1K, 2K, 4K 또는 정확한 픽셀 크기의 이미지를 생성하거나 편집하고, 프롬프트로 짧은 GIF 애니메이션도 만듭니다. 렌더링마다 사용한 토큰으로 과금되며, quality 설정으로 출력 토큰을 정합니다.

• 토큰으로 과금됩니다. 텍스트 입력, 이미지 입력, 출력 토큰에 1M 토큰당 요금이 적용됩니다. 아래 이미지당 가격은 medium 품질 기준 추정치입니다.
• quality는 렌더링에 쓰이는 출력 토큰 수, 즉 가격을 정합니다. 값이 낮을수록 저렴합니다. 생략하면 medium입니다.
• 비동기 방식만 지원합니다. POST /v1/images/tasks로 작업을 만든 뒤 GET /v1/tasks/{task_id}를 폴링하세요. 렌더링은 BeatAPI 측에서 실행되므로 오래 걸려도 연결을 붙잡고 있지 않습니다. 이 모델에서는 동기식 POST /v1/images/generations를 사용할 수 없습니다.
• 작업 하나에 이미지 한 장입니다. 여러 장이 필요하면 작업을 여러 개 만드세요.
• 텍스트로 이미지를 만들거나, 공개 HTTPS 링크로 전달한 최대 16장의 참조 이미지를 편집·합성합니다.
• resolution과 aspect_ratio로 프레임을 정하거나, 1536x1024 같은 정확한 size 하나로 정합니다. 두 가지를 함께 쓸 수는 없습니다.
• output_format: "gif"는 프롬프트만으로 프레임당 200 ms, 9프레임짜리 애니메이션을 만듭니다. size로 프레임 크기(512–960 px)를 정합니다. 정지 이미지와 마찬가지로 토큰 단위로 과금됩니다.

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델 ID

고정 가격 -beta 모델과 이 모델은 quality와 GIF의 프레임 size를 제외하면 같은 요청을 받으며, 가격 계산 방식만 다릅니다. 아래 값은 게이트웨이 계약에서 그대로 가져왔습니다.

엔드포인트와 인증

POST https://api.beatapi.io/v1/images/tasks

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

입력 모드

요청 파라미터

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

"size": "1536x1024"

"quality": "low"

"output_format": "gif"

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

• size는 WIDTHxHEIGHT 형식이며 resolution과 aspect_ratio를 대신합니다. 두 변 모두 16의 배수이면서 16-3840 px, 전체 655,360-8,294,400픽셀, 최대 3:1
• size는 등급이 아니라 렌더링에 쓰인 토큰으로 과금됩니다
• quality는 출력 토큰 수, 즉 가격을 정하며 기본값은 medium입니다
• 렌더링마다 사용한 토큰(텍스트 입력, 이미지 입력, 출력)에 표시된 토큰당 요금으로 과금됩니다. 표시된 이미지당 가격은 medium 품질 기준 추정치입니다
• output_format gif는 프레임당 200 ms, 9프레임짜리 애니메이션을 만듭니다. size로 각 프레임 크기를 정하며, 두 변 모두 16의 배수이면서 512-960 px여야 합니다(9개 프레임은 3x3 시트 하나로 렌더링). size를 생략하면 모델이 정합니다. 이때 resolution과 aspect_ratio는 생략하세요
• gif는 프롬프트만으로 만듭니다. images를 받을 수 없으며 frame_count와 frame_duration_ms도 지원하지 않습니다
• gif는 정지 이미지와 마찬가지로 3x3 프레임 시트에 쓰인 토큰으로 과금됩니다
• 토큰 단위로 과금되는 공식 버전입니다. quality로 low, medium, high, xhigh, max를 받고 GIF 크기를 직접 고를 수 있으며, gpt-image-2.6-sunburst-beta(이미지당 고정 가격)는 둘 다 지원하지 않습니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

• 참조 이미지: PNG, JPEG, WebP(파일 내용으로 판별), 각 최대 50 MB(10진 메가바이트, 호스트가 크기를 알려 줄 때 검사), 링크 1~16개. GIF, HEIC, SVG는 거부됩니다.
• 참조 이미지 자체의 픽셀 수나 화면비 제한은 검사하지 않습니다.
• 호스트가 제시간에 응답하지 않아도 생성 시점에 링크를 거부하지는 않습니다. 작업이 실행될 때 게이트웨이가 다시 가져오며, 그때도 가져올 수 없으면 작업이 실패하고 환불됩니다.
• 로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.
• GIF(output_format: "gif")는 참조 이미지를 받지 않습니다.

프레임 선택: resolution과 aspect_ratio, 또는 size

이미지의 크기와 모양을 지정하는 방법은 두 가지이며, 서로 함께 쓸 수 없습니다.

• 등급과 비율. resolution(1K, 2K 또는 4K)을 보내고, 원하는 모양이 있으면 aspect_ratio도 보냅니다. 둘 다 생략하면 1K와 auto, 즉 정사각형 프레임이 됩니다.
• 정확한 크기. size만 보냅니다(예: 1536x1024). 픽셀 수에 따라 출력 토큰이 달라지며, 작업이 정산되기 전까지는 해당 등급 기준으로 보류됩니다(위 조합 규칙 참고).

size를 resolution 또는 aspect_ratio와 함께 보내면 "size" already fixes the output; do not send "resolution" with it(또는 "aspect_ratio")으로 거부됩니다. 다른 필드가 기본값이어도 마찬가지입니다.

GIF는 둘 다 받지 않습니다. resolution이나 aspect_ratio가 없으며, size는 프레임 하나의 크기(512~960 px)입니다.

GIF 애니메이션 만들기

"output_format": "gif"를 보내고 prompt에 피사체와 움직임을 설명하세요. 결과는 프레임당 200 ms, 9프레임짜리 짧은 GIF 애니메이션입니다.

• 프롬프트만으로 만듭니다. images는 gpt-image-2.6-sunburst output_format "gif" is made from the prompt alone: leave out "images"로 거부됩니다.
• 프레임 크기를 고를 수 있습니다. size는 프레임 하나의 크기입니다. 두 변 모두 16의 배수이면서 512~960 px여야 합니다(예: 768x768). 9개 프레임을 3x3 시트 하나로 렌더링하므로 프레임 하나는 정지 이미지보다 작습니다. size를 생략하면 모델이 정합니다. 범위를 벗어난 size는 a gif frame's "size" edges must be between 512 and 960 pixels: its nine frames are rendered as one 3x3 sheet로 거부됩니다.
• 해상도와 비율은 없습니다. resolution과 aspect_ratio는 생략하세요. resolution을 1K 이외의 값으로, aspect_ratio를 auto 이외의 값으로 보내면 gpt-image-2.6-sunburst output_format "gif" has a fixed size: leave out "resolution"으로 거부됩니다(보낸 필드가 표시됨).
• 프레임 제어 옵션이 없습니다. frame_count와 frame_duration_ms는 지원하지 않습니다: unknown field: frame_count.
• 토큰 단위로 과금됩니다. GIF는 정지 이미지와 마찬가지로 3x3 프레임 시트에 쓰인 토큰으로 과금됩니다(요금은 아래 표 참고).

이 페이지는 애니메이션이 반복 재생된다고 보장하지 않습니다. 저장된 파일의 mime_type은 image/gif입니다.

제출 후 폴링

이 모델은 작업으로만 실행됩니다. POST /v1/images/tasks는 data.id에 작업 ID를 담아 즉시 응답합니다. 그다음 data.status가 succeeded 또는 failed가 될 때까지 data.poll_after_seconds마다 GET /v1/tasks/{task_id}를 호출하세요. 렌더링은 BeatAPI 측에서 실행되므로 오래 걸려도 연결을 붙잡거나 클라이언트 시간 제한에 걸리지 않습니다. 이 모델에서는 동기식 POST /v1/images/generations를 사용할 수 없습니다.

# 1. Create the task. The call returns at once; the task ID is in data.id.
TASK_ID=$(curl -sS -X POST https://api.beatapi.io/v1/images/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.6-sunburst","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"2K","quality":"medium"}' | jq -r '.data.id')
# 2. Poll until the task is final. The render runs on BeatAPI, not on this connection.
while true; do
  TASK=$(curl -sS "https://api.beatapi.io/v1/tasks/$TASK_ID" -H "Authorization: Bearer $BEATAPI_API_KEY")
  STATUS=$(echo "$TASK" | jq -r '.data.status')
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 5
done
echo "$TASK" | jq '.data.output.media[].url, .data.usage'

Capabilities API에서도 방식은 같습니다. POST /v1/capabilities/run으로 시작한 다음, 반환된 작업 ID로 succeeded 또는 failed가 될 때까지 상태 조회를 보내세요.

{"reference":"model:gpt-image-2.6-sunburst","input":{"model":"gpt-image-2.6-sunburst","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"2K","quality":"medium"}}

{"reference":"model:gpt-image-2.6-sunburst","operation":"status","task_id":"<task_id>"}

토큰 과금과 고정 가격 비교

이 모델이 받지 않는 필드

이미지 엔드포인트는 다른 이미지 모델이나 다른 API가 사용하는 필드도 몇 가지 알고 있습니다. 이 모델에서 그런 필드를 보내면 무시하지 않고 거부하므로, 효과 없는 설정에 비용을 내는 일이 없습니다.

• background, seed, enhance_prompt → field "background" is not supported by model gpt-image-2.6-sunburst(보낸 필드와 호출한 모델 포함). GPT Image 2.6에는 background 필드가 없으므로 투명 배경을 요청할 수 없습니다.
• n, moderation, frame_count 같은 그 밖의 알 수 없는 필드 → unknown field: n. n은 없습니다. 작업 하나에 이미지 한 장 또는 GIF 하나입니다.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
}'

텍스트로 이미지 생성

등급과 비율을 지정해 프롬프트로 만드는 2K 가로 이미지입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
}'

낮은 품질로 초안 만들기

quality: "low"와 1K로 보내는 첫 번째 요청으로, 출력 토큰을 적게 써서 비용이 낮습니다. 초안과 미리 보기에 적합합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "1K",
  "quality": "low"
}'

이미지 한 장 편집

제품은 유지하고 배경만 바꿉니다. auto는 정사각형으로 렌더링하므로 모양을 명시합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

여러 이미지 합성

프롬프트에서 각 참조 이미지를 순서로 지칭하세요.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

정확한 크기

1536x1024 프레임입니다. size는 단독으로 사용하며 resolution도 aspect_ratio도 보내지 않습니다. 1K 추정 금액으로 보류됩니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "1536x1024"
}'

GIF 애니메이션

프롬프트만으로 만드는 9프레임짜리 애니메이션입니다. images, resolution, aspect_ratio는 보내지 않습니다. size로 각 프레임 크기를 정합니다. 토큰 단위로 과금됩니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A paper boat drifting on gentle blue waves, flat illustration, soft morning light",
  "output_format": "gif",
  "size": "768x768"
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.077328,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.077328
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.077328,
      "credits_settled": 0.077328,
      "credits_refunded": 0,
      "credits_charged": 0.077328
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.077328,
      "credits_settled": 0,
      "credits_refunded": 0.077328,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

• 아래 표의 1M 토큰당 요금으로 텍스트 입력(프롬프트), 이미지 입력(images의 참조 이미지), 출력(이미지) 토큰을 과금합니다. 토큰 수는 모델이 계산하며, quality, 프레임, 참조 이미지에 따라 모두 달라집니다.
• 이미지당 가격은 참조 이미지 없이 각 등급의 정사각형 프레임을 medium 품질로 한 번 렌더링한 추정치입니다. low는 출력 토큰을 더 적게, 높은 값은 더 많이 씁니다.
• 작업이 생성되면 해당 등급의 추정 금액이 잔액에서, 키에 한도가 있다면 키 한도에서도 보류됩니다. 작업이 성공하면 실제로 쓴 토큰으로 정산되므로 최종 data.usage는 보류 금액과 다를 수 있습니다. 작업이 생기기 전에 거부된 요청은 비용이 들지 않습니다.
• 실패한 작업은 전액 환불됩니다.
• GIF는 정지 이미지와 마찬가지로 3x3 프레임 시트에 쓰인 토큰으로 과금됩니다.
• 고정 가격 gpt-image-2.6-sunburst-beta 라인은 GPT Image 2.6을 렌더링 사용량과 관계없이 크기 등급별 이미지당 고정 가격과 GIF당 가격으로 판매합니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

자주 발생하는 오류

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}