Seedream 5.0 Pro

텍스트와 최대 10장의 참조 이미지로 1K 또는 2K 이미지를 생성하거나 편집합니다.

• 비동기 방식입니다. 생성 요청은 곧바로 작업 ID를 반환하며, 작업이 성공하면 이미지가 도착합니다.
• 작업 하나에 이미지 한 장입니다. 여러 장이 필요하면 작업을 여러 개 만드세요.
• 텍스트로 이미지를 만들거나, 공개 HTTPS 링크로 전달한 최대 10장의 참조 이미지를 편집·합성합니다.
• resolution(1K 또는 2K)에 따라 이미지당 가격이 정해지며, images의 참조 이미지마다 소액이 추가됩니다. 4K 등급은 없습니다.
• 실패한 작업은 비용이 들지 않습니다. 보류 금액은 전액 환불됩니다.

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

엔드포인트와 인증

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"
]

입력 미디어 제한

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

• 참조 이미지: 공개 HTTPS 링크 1~10개.
• BeatAPI는 작업을 만들 때 이 링크를 내려받거나 형식, 크기, 픽셀 크기를 검사하지 않으므로, 잘못된 링크라도 미리 거부되지 않습니다. 각 링크는 모델이 직접 가져옵니다.
• 모델이 가져오거나 읽을 수 없는 링크는 작업이 생성된 뒤 실패하며(보통 bad_request), 해당 작업은 환불됩니다. 로그인 없이 서버 요청에 응답하는 호스트의 일반 이미지 파일 직접 링크를 사용하세요.
• 로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

이 모델이 받지 않는 필드

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

• quality, seed, background, size, enhance_prompt → field "quality" is not supported by model seedream-5-pro(보낸 필드 포함).
• n 같은 그 밖의 알 수 없는 필드 → unknown field: n. n은 없습니다. 작업 하나에 이미지 한 장입니다.

요청에 잘못된 필드가 여러 개 있어도 메시지에는 하나만 표시됩니다. 고친 뒤 다시 보내세요.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-pro",
  "prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
  "resolution": "2K"
}'

텍스트로 이미지 생성

프롬프트로 만드는 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": "seedream-5-pro",
  "prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
  "resolution": "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": "seedream-5-pro",
  "prompt": "Keep the bottle exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "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": "seedream-5-pro",
  "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"
  ],
  "resolution": "2K"
}'

2K JPEG 포스터

JPEG으로 받는 포스터입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-pro",
  "prompt": "A retro travel poster of a coastal city at sunset, bold flat colours, large title text \"SEASIDE\" at the top",
  "resolution": "2K",
  "output_format": "jpeg"
}'

응답

작업 생성(201)

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "seedream-5-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "seedream-5-pro",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.042,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.042
    },
    "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": "seedream-5-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "seedream-5-pro",
    "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.042,
      "credits_settled": 0.042,
      "credits_refunded": 0,
      "credits_charged": 0.042
    },
    "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": "seedream-5-pro",
    "capability_version": 1,
    "media_type": "image",
    "model": "seedream-5-pro",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.042,
      "credits_settled": 0,
      "credits_refunded": 0.042,
      "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": "seedream-5-pro",
  "prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
  "resolution": "2K"
})
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"])

과금

• 작업 하나에 이미지 한 장이며, resolution에 따라 가격이 정해집니다(아래 표). 가격표에는 해상도별로 행이 하나씩 있으며, 참조 이미지에 대한 별도 요금은 없습니다.
• 가격은 작업 생성 시 잔액에서, 키에 한도가 있다면 키 한도에서도 보류됩니다. 작업이 생기기 전에 거부된 요청은 비용이 들지 않습니다.
• 성공한 작업은 보류 금액이 그대로 청구됩니다. 실패한 작업은 전액 환불되어 credits_refunded가 credits_reserved와 같아지고, credits_charged와 credits_settled는 0이 됩니다.

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

자주 발생하는 오류

HTTP 오류 요약

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

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