이미지 API

고정된 BeatAPI 모델 ID로 비동기 이미지 생성 작업을 하나 만듭니다.

모델 이름으로 과금 방식을 알 수 있습니다. -beta는 이미지당 고정 가격의 저가 라인입니다. 공식 버전은 토큰 단위로 과금되며, GPT Image 2.6은 접미사 없는 이름(예: gpt-image-2.6-flare), 이전 계열은 -std(예: gpt-image-2-std)를 씁니다. quality 옵션은 공식 GPT Image 버전에서만 받습니다.

필드, 기본값, 열거값, 조합 규칙, 요청 예시, 응답, 오류 동작은 각 모델 페이지에서 확인하세요.

사용 가능한 모델 목록

GET /v1/media/models

이 공개 엔드포인트는 인증이 필요하지 않습니다.

curl "https://api.beatapi.io/v1/media/models?media_type=image"

{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "gpt-image-2",
        "object": "generation_model",
        "name": "GPT Image 2",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-flare",
        "object": "generation_model",
        "name": "GPT Image 2.5 Flare",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-sunburst",
        "object": "generation_model",
        "name": "GPT Image 2.5 Sunburst",
        "media_type": "image",
        "input_modes": ["text", "image"]
      }
    ]
  }
}

내부 라우팅은 공개 계약에 포함되지 않습니다.

공통 생성 계약

POST /v1/images/tasks

본문은 정확히 하나의 모델 스키마와 일치해야 합니다. model이 구분자이며, 알 수 없는 필드는 거부됩니다.

curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph on a warm stone pedestal.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

올바른 요청은 data.id, task_kind="image", 선택된 model, status="queued", 사용량 지표, request_id와 함께 201 Created를 반환합니다. succeeded 또는 failed가 될 때까지 5~10초마다 GET /v1/tasks/{task_id}를 폴링하세요. 성공한 이미지는 data.output.media[]와 data.output.r2_url에 있습니다.

완전히 같은 멱등 재요청은 이미 접수된 작업을 반환합니다. 같은 키를 다른 본문으로 재사용하면 409 idempotency_conflict가 반환됩니다.

공통 오류

오류 응답에는 error.code, 영어 error.message, error.retryable, error.request_id, 그리고 429일 때 error.retry_after_seconds가 포함됩니다. 접수된 뒤 실패한 작업도 조회하면 200을 반환하며, 실패 코드는 data.error_code에 있습니다. 모든 코드와 재시도 규칙은 오류를 참고하세요. 실제로 적용되는 요청 계약은 아래 각 모델 페이지에 있습니다.