> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream API 이미지 생성·편집: 가격과 사용법

> Seedream 5.0 Flash($0.018부터), 5.0 Pro, 5.0, 4.5, 4.0으로 이미지를 만들고 편집하며, 참조 이미지 최대 10장 조합과 투명 레이어 분리까지 LaoZhang API 하나로 호출하는 방법을 안내합니다.

Seedream 5.0 Flash는 가장 최신이자 가장 저렴한 Seedream 모델이고, 5.0 Pro는 화질이 가장 높은 모델입니다. 생성과 편집이 같은 JSON 엔드포인트를 쓰며, 요금은 출력 이미지 한 장 단위로 매겨집니다.

참조 이미지에는 요금이 붙지 않습니다. 예외는 5.0 Pro로, 두 번째 참조 이미지부터 한 장당 \$0.003이 추가됩니다. 아래는 2026년 9월 25일 기준 공개 가격입니다([AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md) 참고).

| 모델 ID | 버전 | 이미지당 가격 |
| - | - | - |
| `seedream-5-0-flash-260915` | Seedream 5.0 Flash(최신) | \$0.018 |
| `seedream-5-0-pro-260628` | Seedream 5.0 Pro | \$0.12 |
| `seedream-5-0-260128` | Seedream 5.0 | \$0.035 |
| `seedream-4-5-251128` | Seedream 4.5 | \$0.045 |
| `seedream-4-0-250828` | Seedream 4.0 | \$0.035 |

모든 Seedream 요청은 같은 엔드포인트와 JSON 본문 형식을 사용합니다.

* 엔드포인트: `POST https://api.laozhang.ai/v1/images/generations`
* 이미지 생성: 프롬프트만 보냅니다.
* 이미지 편집·합성: `image`에 참조 이미지를 1\~10장 넣습니다.
* 동시 요청: 플랫폼 차원의 제한이나 스로틀링은 없습니다. `429`는 업스트림 용량 때문에 발생하며, 자세한 내용은 [동시 요청과 429](https://docs.laozhang.ai/ko/faq/api-concurrency.md)를 참고하세요.

![Seedream 5.0으로 생성한 사실적인 산 위의 일몰](https://mintcdn.com/laozhangai-edd05f2c/YuJHjB7ivlJQODe0/images/samples/seedream-generate.jpg?fit=max\&auto=format\&n=YuJHjB7ivlJQODe0\&q=85\&s=58c254e27cd42e2b29f5a2cbf1efba30)

아래 생성 예제의 출력: Seedream 5.0, 2K. 프롬프트: A beautiful sunset over mountains, realistic style

이 페이지의 예제는 Seedream 5.0(`seedream-5-0-260128`)을 사용합니다. 다른 버전을 호출하려면 다음을 바꾸세요.

* **4.5 또는 4.0**: `model`만 바꿉니다.
* **5.0 Flash 또는 5.0 Pro**: `model`을 바꾸고, 요청에 `sequential_image_generation`과 `stream`이 없는지 확인합니다. 두 모델은 이 필드가 있으면 HTTP 400을 반환합니다. 아래 편집 예제에는 `"sequential_image_generation": "disabled"`가 들어 있으니 이 줄을 먼저 지우세요.

## 시작하기 전에

**1. 건당 과금 모델용 API 키 발급**

Seedream은 건당 과금(按次) 모델입니다. [토큰 관리](https://api.laozhang.ai/token)에서 API 키(콘솔에서는 '토큰'이라고 부릅니다)를 새로 만들거나 기존 키를 편집해 **과금 방식**(计费模式)을 **사용량 우선**(按量优先, 권장) 또는 **건당 과금**(按次计费)으로 설정합니다. 사용량 우선 키는 사용량 과금 모델도 호출할 수 있고, 건당 과금 키는 건당 과금 모델만 호출할 수 있습니다.

키는 서버 측 환경 변수에 보관하세요.

![토큰 관리에서 과금 방식을 건당 과금(按次计费)으로 설정하고 만들기를 눌러 토큰을 생성하는 화면](https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max\&auto=format\&n=_loZ0Jy0ZI__xJ9z\&q=85\&s=1fdceb804bb3ad50f83a21ec65b4d807)

**2. 환경 설정**

키를 환경 변수로 설정하고, Python 예제에서 쓰는 `requests`를 설치합니다.

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install requests
```

## 이미지 생성

워터마크 없는 2K 이미지를 만들고 응답을 `seedream-generation.json`에 저장하는 요청입니다.

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A beautiful sunset over mountains, realistic style",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-generation.json
```

요청이 성공하면 `data`에 이미지가 담겨 옵니다.

```json theme={null}
{
  "created": 1726051200,
  "data": [
    {
      "url": "https://example.com/generated_image.jpg"
    }
  ]
}
```

### 결과 저장

응답을 받으면 바로 이미지를 내려받으세요. 아래 스크립트를 `save_images.py`로 저장하면, 응답에 들어 있는 모든 이미지를 `url`이든 `b64_json`이든 형식에 관계없이 저장합니다.

```python save_images.py theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"{response_file}에 이미지가 없습니다: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # data:image/...;base64, 접두사가 있으면 떼고, 빠진 패딩을 채웁니다.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"저장 완료: {path}")
```

```bash theme={null}
python3 save_images.py seedream-generation.json seedream-sunset
```

`저장 완료: seedream-sunset-1.jpg` 같은 줄이 출력되면 파일을 열어 결과를 확인하세요.

### Python으로 생성하기

```python theme={null}
import base64
import os
from pathlib import Path

import requests

response = requests.post(
    "https://api.laozhang.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "model": "seedream-5-0-260128",
        "prompt": "A beautiful sunset over mountains, realistic style",
        "size": "2K",
        "response_format": "url",
        "watermark": False,
    },
    timeout=180,
)
response.raise_for_status()
item = response.json()["data"][0]

if item.get("b64_json"):
    value = item["b64_json"].split(",", 1)[-1]
    image = base64.b64decode(value + "=" * (-len(value) % 4))
else:
    download = requests.get(item["url"], timeout=120)
    download.raise_for_status()
    image = download.content

extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"seedream-sunset.{extension}")
output.write_bytes(image)
print(f"저장 완료: {output}")
```

## 이미지 편집

요청에 `image`를 추가하면 기존 이미지를 편집하거나 다시 그립니다. 이 예제는 BytePlus 문서의 공개 샘플 이미지를 쓰므로 그대로 실행할 수 있습니다.

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "무성한 잔디 위에 엎드려 있는 강아지를 클로즈업한 이미지를 만들어 주세요.",
    "image": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/seedream4_imageToimage.png",
    "sequential_image_generation": "disabled",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-edit.json

python3 save_images.py seedream-edit.json seedream-edit
```

## 참조 이미지 최대 10장 조합

참조 이미지를 여러 장 쓰려면 `image`를 배열로 보냅니다. 각 항목은 공개 URL이거나 `data:image/png;base64,...` 같은 data URL입니다. 이미지는 배열 순서대로 번호가 매겨지므로 프롬프트에서 이미지 1, 이미지 2처럼 가리킬 수 있습니다.

다음 예제는 로컬 파일 세 개를 data URL로 보냅니다.

```bash theme={null}
IMG1=$(base64 < product.png | tr -d '\n')
IMG2=$(base64 < scene.jpg | tr -d '\n')
IMG3=$(base64 < style.jpg | tr -d '\n')

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o seedream-multi-edit.json <<EOF
{
  "model": "seedream-5-0-260128",
  "prompt": "이미지 1의 제품을 이미지 2의 장면에 배치하고, 이미지 3의 조명과 색감을 적용하세요. 제품의 형태, 라벨, 색상은 그대로 유지하세요.",
  "image": [
    "data:image/png;base64,$IMG1",
    "data:image/jpeg;base64,$IMG2",
    "data:image/jpeg;base64,$IMG3"
  ],
  "sequential_image_generation": "disabled",
  "size": "2K",
  "response_format": "url",
  "watermark": false
}
EOF

python3 save_images.py seedream-multi-edit.json seedream-multi-edit
```

### Python으로 참조 이미지 조합하기

아래 함수는 참조 이미지를 1\~10장 받아, 로컬 파일은 data URL로 바꾸고 공개 URL은 그대로 전달합니다.

```python theme={null}
import base64
import mimetypes
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_image_input(source):
    """URL은 그대로 반환하고, 로컬 파일은 data URL로 변환합니다."""
    if source.startswith(("https://", "http://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def seedream_edit(prompt, sources, model="seedream-5-0-260128"):
    if not 1 <= len(sources) <= 10:
        raise ValueError("Seedream 참조 이미지는 1~10장이어야 합니다")
    images = [to_image_input(source) for source in sources]
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "model": model,
            "prompt": prompt,
            "image": images[0] if len(images) == 1 else images,
            "sequential_image_generation": "disabled",
            "size": "2K",
            "response_format": "url",
            "watermark": False,
        },
        timeout=180,
    )
    response.raise_for_status()
    return response.json()


def save_all_images(result, stem):
    """data[]의 모든 항목을 저장합니다. 연속 생성은 이미지를 여러 장 반환할 수 있습니다."""
    paths = []
    for number, item in enumerate(result["data"], start=1):
        if item.get("b64_json"):
            value = item["b64_json"].split(",", 1)[-1]
            image = base64.b64decode(value + "=" * (-len(value) % 4))
        else:
            download = requests.get(item["url"], timeout=120)
            download.raise_for_status()
            image = download.content
        extension = "png" if image.startswith(b"\x89PNG") else "jpg"
        path = Path(f"{stem}-{number}.{extension}")
        path.write_bytes(image)
        paths.append(path)
    return paths


result = seedream_edit(
    "이미지 1의 제품을 이미지 2의 장면에 배치하고, 이미지 3의 조명과 색감을 적용하세요. "
    "제품의 형태, 라벨, 색상은 그대로 유지하세요.",
    ["product.png", "scene.jpg", "style.jpg"],
)
for path in save_all_images(result, "seedream-python-edit"):
    print("저장 완료:", path)
```

## 이미지를 투명 레이어로 분리

Seedream 5.0 Flash(`seedream-5-0-flash-260915`)와 5.0 Pro(`seedream-5-0-pro-260628`)는 완성된 이미지 한 장을 배경과 투명 PNG 레이어 여러 장으로 분해합니다. 레이어 하나에 요소 하나가 담기므로 배경 교체, 레이아웃 재배치, 요소 재사용에 활용할 수 있습니다.

두 모델 모두 반환한 이미지마다 과금하며, Pro는 이미지당 가격이 Flash의 약 6.7배이므로 Flash부터 시작하세요. 일반 프롬프트로 투명 배경을 요청해도 알파 채널은 생기지 않습니다. 알파 채널이 필요하면 레이어 분해를 쓰세요.

레이어 요청은 일반 편집과 다음 점이 다릅니다.

* `layer_decomposition`을 `true`로 설정합니다.
* `image`에는 이미지를 정확히 한 장만 문자열 또는 항목 하나짜리 배열로 보냅니다.
* `prompt`는 선택입니다. 생략하거나 빈 문자열을 보내면 모델이 주요 요소를 스스로 찾습니다.
* `size`는 `1K`로 설정합니다. 정확한 픽셀 값은 받지 않습니다.
* 레이어 요청이 받는 해상도 단계는 `1K`, `1.5K`, `2K`, `auto`뿐입니다.
* 5.0 Flash와 5.0 Pro만 지원합니다. `seedream-5-0-260128`과 `seedream-4-5-251128`에서는 오류 코드 `InvalidParameter`와 함께 HTTP 400을 반환합니다.

### 레이어 요청 보내기

```bash theme={null}
curl --fail-with-body --max-time 360 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash-260915",
    "image": "https://example.com/your-poster.jpg",
    "layer_decomposition": true,
    "size": "1K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-layers.json
```

`image` URL은 공개적으로 내려받을 수 있는 자신의 이미지로 바꾸거나 data URL로 보내세요. 5.0 Pro를 쓰려면 `model`만 바꾸면 됩니다.

> [!WARNING]
>
> **레이어 분해는 반환된 이미지마다 과금합니다. Flash는 장당 \$0.018, Pro는 장당 \$0.12입니다.**
>
> * 레이어 수는 모델이 정하며, 같은 이미지라도 실행할 때마다 달라질 수 있습니다. 영화 포스터가 6장(배경 1장, 레이어 5장)으로 나뉘면 Flash는 \$0.108, Pro는 \$0.72입니다. 요소가 많은 이미지는 십여 장 이상이 나올 수 있으며, Flash에서 16장이면 \$0.288입니다.
> * `1K`에서 6장 결과는 Flash가 1분 미만, Pro가 약 70초 걸리며 레이어가 많을수록 오래 걸립니다. 클라이언트 타임아웃은 300초 이상으로 잡으세요. 2K 요청은 오래 걸릴 수 있고, 클라이언트 연결이 끊겨도 과금됩니다.
> * 분해할 수 없는 이미지는 HTTP 400을 반환하며 과금되지 않습니다. 다시 시도해도 됩니다.
> * 모델이 제거된 요소 뒤쪽 영역을 새로 그려 채우므로, 상업적으로 쓰기 전에 배경을 확인하세요.

### 레이어 응답 읽기

`data[]`의 첫 항목은 배경이고, 나머지 항목은 각각 레이어 하나입니다. 아래 응답은 배경과 레이어 하나만 남기고 줄인 것입니다.

```json theme={null}
{
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "896x1200",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer.png",
      "size": "916x529",
      "output_format": "png",
      "z_index": 4,
      "bounding_box": {
        "absolute": [260, 716, 619, 924],
        "normalized": [290, 597, 690, 769]
      },
      "name": "Spaceship",
      "description": "Sci-fi spaceship with blue engine glow effects, separate from the background nebula."
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 6
  }
}
```

| 필드 | 의미 |
| - | - |
| `url` | 임시 다운로드 링크이므로 빨리 저장하세요. CORS 헤더가 없으므로 브라우저 클라이언트는 `"response_format": "b64_json"`을 요청해 `b64_json` 필드에서 이미지를 읽으세요 |
| `size` | 이 이미지 파일의 픽셀 크기 |
| `output_format` | 배경은 요청의 `output_format`(기본값 `jpeg`)을 따르고, 레이어는 항상 RGBA `png` |
| `z_index` | 쌓는 순서. 배경은 0, 레이어는 1부터이며 값이 클수록 위에 놓임 |
| `bounding_box.absolute` | 배경 위 레이어 위치. 배경 픽셀 기준 `[left, top, right, bottom]` |
| `bounding_box.normalized` | 같은 상자를 0\~1000 척도로 나타낸 값 |
| `name`, `description` | 모델이 레이어마다 붙이는 영어 이름과 설명. 배경에는 없음 |
| `usage.generated_images` | 배경을 포함해 반환된 이미지 수 |

`usage`에는 `output_tokens`도 있지만, 요금은 이미지 수로만 정해집니다.

레이어 파일 크기가 bounding box 크기와 같지는 않습니다. 예시에서 916×529 PNG는 359×208 상자에 들어가므로, 이미지를 다시 합칠 때는 각 레이어를 `absolute` 상자 크기에 맞게 조정하세요.

### 레이어 저장과 이미지 재합성

이 스크립트는 `seedream-layers.json`을 읽어 각 이미지를 `z_index`와 이름이 들어간 파일명으로 저장하고, Pillow로 각 레이어를 배경 위 `bounding_box.absolute` 위치에 붙입니다. 먼저 `python3 -m pip install pillow`로 Pillow를 설치하세요.

```python save_layers.py theme={null}
import json
import re
import sys
import urllib.request
from io import BytesIO
from pathlib import Path

from PIL import Image

response = json.loads(Path(sys.argv[1]).read_text())
canvas = None

# z_index가 낮은 것부터: 배경을 먼저 놓고 그 위에 레이어를 쌓습니다.
for item in sorted(response["data"], key=lambda item: item["z_index"]):
    with urllib.request.urlopen(item["url"], timeout=120) as download:
        content = download.read()
    name = re.sub(r"[^a-z0-9]+", "-", item.get("name", "base").lower()).strip("-")
    extension = "png" if item["output_format"] == "png" else "jpg"
    path = Path(f"layer-{item['z_index']:02d}-{name or 'layer'}.{extension}")
    path.write_bytes(content)
    print(f"저장 완료: {path}")

    image = Image.open(BytesIO(content)).convert("RGBA")
    if "bounding_box" not in item:
        canvas = image  # 배경에는 bounding_box가 없습니다.
        continue
    left, top, right, bottom = item["bounding_box"]["absolute"]
    layer = image.resize((right - left, bottom - top), Image.LANCZOS)
    canvas.alpha_composite(layer, (left, top))

canvas.save("recomposited.png")
print("저장 완료: recomposited.png")
```

```bash theme={null}
python3 save_layers.py seedream-layers.json
```

`layer-00-base.jpg`, `layer-04-spaceship.png` 같은 파일과 `recomposited.png`가 만들어집니다. 배경을 바꾸거나 요소를 빼려면, 합성하기 전에 배경 파일을 교체하거나 해당 레이어를 건너뛰세요.

## 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | 이 페이지 상단 표의 모델 ID. 예: `seedream-5-0-flash-260915`, `seedream-5-0-260128` |
| `prompt` | string | 예 | 이미지 설명 또는 편집 지시. 레이어 분해에서는 선택 |
| `image` | string 또는 array | 편집 시 | 참조 이미지 1장은 문자열, 최대 10장은 배열. 각 항목은 공개 URL 또는 data URL. 레이어 분해는 정확히 1장 |
| `size` | string | 아니요 | 출력 크기. 예제는 `2K`를 사용합니다. 모델마다 지원 단계가 다르며, 아래 자주 묻는 질문에 정리했습니다 |
| `response_format` | string | 아니요 | `url`(기본값) 또는 `b64_json` |
| `output_format` | string | 아니요 | 5.0 Flash, 5.0 Pro, 5.0에서 `png` 또는 `jpeg`. 레이어 분해에서는 배경 형식만 정합니다 |
| `watermark` | boolean | 아니요 | `false`면 워터마크를 넣지 않습니다 |
| `sequential_image_generation` | string | 아니요 | `disabled`(기본값)는 예제처럼 이미지 1장을 반환하고, `auto`는 모델이 반환 장수를 정하는 연속 생성을 켭니다. 5.0 Flash와 5.0 Pro는 지원하지 않습니다 |
| `layer_decomposition` | boolean | 아니요 | 5.0 Flash와 5.0 Pro 전용. `true`면 참조 이미지 1장을 배경과 투명 레이어로 분리합니다. 위의 투명 레이어 분리 절을 참고하세요 |

5.0 Flash와 5.0 Pro는 요청에 `sequential_image_generation`(`"disabled"` 포함)이나 `stream`이 있으면 HTTP 400을 반환합니다. 또한 `n`을 무시하므로, 레이어 분해가 아니면 요청 하나에 이미지 1장이 반환됩니다.

연속 생성과 레이어 분해는 응답 하나에 이미지를 여러 장 담을 수 있습니다. `save_images.py`, `save_all_images`, `save_layers.py`처럼 `data[]`의 모든 항목을 저장하세요.

## 자주 묻는 질문

### 어떤 Seedream 버전을 써야 하나요?

작업에 필요한 것으로 고르세요.

* **낮은 가격, 빠른 속도, 대량 처리**: Seedream 5.0 Flash(`seedream-5-0-flash-260915`), 이미지당 \$0.018. BytePlus는 광고 소재, 제품 이미지, 텍스트가 들어간 포스터나 디자인용으로 안내합니다.
* **최고 화질**: Seedream 5.0 Pro(`seedream-5-0-pro-260628`). 사실적인 인물, 세밀한 재질 표현, 복잡한 지시에 적합합니다. 이미지당 \$0.12로 5.0의 약 3.4배이고 속도도 느리므로, 일상 작업에는 5.0이나 Flash를 쓰세요.
* **3K 출력, 연속 생성, 스트리밍**: Seedream 5.0(`seedream-5-0-260128`). BytePlus 문서에서는 Seedream 5.0 lite라고 부르며, `2K`와 `3K`를 지원하고 최대 3K입니다.
* **4K**: Seedream 4.5(`seedream-4-5-251128`) 또는 4.0(`seedream-4-0-250828`). 그 밖에는 기존 워크플로가 이 두 버전의 출력에 의존할 때만 계속 쓰세요.
* **기존 이미지에서 투명 레이어 추출**: 5.0 Flash의 레이어 분해(위의 투명 레이어 분리 절 참고). 5.0 Pro도 지원하지만 이미지당 가격이 약 6.7배입니다.

모든 버전의 현재 가격은 [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md)에 있습니다.

### `size`에는 어떤 값을 넣나요? 4K도 되나요?

두 방식 중 하나만 쓰세요. 해상도 단계를 보내고 종횡비는 프롬프트에 적거나(예: "16:9 가로 화면"), `2848x1600`처럼 정확한 픽셀을 보냅니다. 모델별 해상도 단계는 다음과 같습니다.

* `seedream-5-0-flash-260915`: `1K`, `1.5K`, `2K`(기본값 2K)
* `seedream-5-0-pro-260628`: `1K`, `2K`
* `seedream-5-0-260128`: `2K`, `3K`(최대 3K)
* `seedream-4-5-251128`: `2K`, `4K`
* `seedream-4-0-250828`: `1K`, `2K`, `4K`

정확한 픽셀 값은 총 픽셀 범위와 종횡비 범위를 모두 만족해야 합니다.

* 최소: 5.0과 4.5는 2560×1440(3,686,400픽셀), 4.0은 1280×720(921,600픽셀)
* 최대: 4.5와 4.0은 4096×4096, 5.0은 3K 단계
* 5.0 Flash: 총 921,600\~4,624,220픽셀
* 5.0 Pro: 최대 약 419만 픽셀. 예: `2048x2048`, 16:9는 `2720x1530`
* 종횡비: 5.0 Flash, 5.0, 4.5, 4.0에서 1/16\~16

그래서 `1024x1024` 같은 작은 크기는 5.0과 4.5에서 실패합니다. 5.0 Flash에 해상도 단계를 보내면 내용에 따라 종횡비를 고르므로, 비율을 고정해야 한다면 `2560x1440`처럼 정확한 픽셀을 보내세요. 5.0 Flash에서 `3K`와 `4K`는 HTTP 400을 반환합니다. 이미지당 가격은 크기와 관계없이 같습니다.

레이어 분해는 `1K`, `1.5K`, `2K`, `auto`만 받으며 정확한 픽셀 값은 받지 않습니다.

### 연속 생성은 어떻게 동작하고 어떻게 과금되나요?

`sequential_image_generation`을 `auto`로 설정하면 모델이 프롬프트를 보고 관련 이미지를 몇 장 반환할지 정합니다. 예를 들어 "같은 캐릭터의 아침, 낮, 밤 모습 세 장"처럼 요청할 수 있습니다.

장수를 제한하려면 BytePlus가 안내하는 `sequential_image_generation_options.max_images`(1\~15)를 쓰세요. 참조 이미지와 생성 이미지를 합쳐 15장을 넘을 수 없습니다.

이때 응답의 `data[]`에 이미지가 여러 장 담기므로 모든 항목을 저장하세요. 반환된 이미지마다 과금되므로 `seedream-5-0-260128`에서 4장이면 \$0.14이고, 참조 이미지는 과금되지 않습니다. 실제 청구 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 확인하세요.

5.0 Flash와 5.0 Pro는 연속 생성을 지원하지 않으며, `"disabled"`를 포함해 `sequential_image_generation` 값이 있으면 HTTP 400을 반환합니다. 연속 생성은 5.0으로 하거나, Flash나 Pro에는 이미지마다 요청을 하나씩 보내세요.

### 로컬 이미지는 어떻게 보내고, 제한은 무엇인가요?

`data:image/png;base64,<Base64 데이터>` 형식의 data URL로 바꿔 보냅니다. 형식 이름은 `png`, `jpeg`처럼 소문자로 씁니다. 위의 Python으로 참조 이미지 조합하기 절에 있는 함수가 이 변환을 대신해 줍니다.

BytePlus가 정한 참조 이미지별 제한은 다음과 같습니다.

* 형식: jpeg, png, webp, bmp, tiff, gif, heic, heif
* 용량: 최대 30MB
* 크기: 가로와 세로 각각 14픽셀 초과, 전체 6000×6000픽셀 이하
* 종횡비: 1/16\~16

공개 URL은 바로 내려받을 수 있어야 합니다. Base64로 인코딩하면 요청 본문이 약 3분의 1 커지므로, 큰 이미지는 공개 URL로 보내는 편이 좋습니다.

### 워터마크는 어떻게 없애나요?

이 페이지의 모든 예제처럼 `"watermark": false`를 보내세요. BytePlus는 `watermark` 기본값이 `true`이고 오른쪽 아래에 "AI generated" 라벨을 넣으므로, 깨끗한 이미지가 필요하면 `false`를 명시하세요.

### 결과 URL은 얼마나 유효한가요? Base64로 받을 수 있나요?

BytePlus에 따르면 이미지 URL은 생성 후 24시간 동안 유효합니다. 응답을 받는 즉시 이미지를 내려받아 사본을 보관하고, 반환된 URL을 영구 주소로 저장하지 마세요.

응답 안에서 이미지를 바로 받으려면 `response_format`을 `b64_json`으로 설정하세요. `save_images.py` 스크립트와 Python 예제는 두 형식을 모두 처리합니다.

### 실패한 요청도 과금되나요?

과금되지 않습니다. 파라미터 오류나 모더레이션 차단처럼 200이 아닌 응답은 과금되지 않으며, 이미지가 반환되었을 때만 요금이 나갑니다.

클라이언트 타임아웃은 실패와 다릅니다. 서버에서는 이미지 생성이 끝나 과금되었을 수 있으니, 다시 보내기 전에 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)를 확인하세요. 실제 청구 내역의 최종 기준은 호출 로그입니다.

아직 처리 중인 요청을 끊지 않도록 모델별로 클라이언트 타임아웃을 설정하세요.

* 5.0 Flash: 60초 이상. BytePlus는 20초 안에 끝난다고 안내하며, 참조 이미지가 10장이면 약 30초 걸립니다.
* 5.0 Pro: 240초 이상. 요청 하나에 보통 약 2분이 걸립니다.
* 5.0 Flash 또는 5.0 Pro의 레이어 분해: `1K` 기준 300초 이상.

## 관련 문서

* [Seedream 5.0 Flash·5.0 Pro 출시 공지](https://docs.laozhang.ai/en/announcements/seedream-5-0-flash-pro-2026-09.md): 가격, 이전 시 주의할 점, 버전 비교
* [이미지 API 비교](https://docs.laozhang.ai/ko/api-capabilities/image-generation-guide.md): Seedream과 다른 이미지 모델 비교
* [Images API](https://docs.laozhang.ai/ko/api-reference/images.md): 공통 요청·응답 형식
* [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md): Seedream 현재 가격과 그룹
* [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md): 요청별 모델과 청구 금액 확인

## 참고 자료

* [BytePlus ModelArk 이미지 생성 API](https://docs.byteplus.com/en/docs/ModelArk/1541523): Seedream 공식 요청 파라미터, `size` 범위, URL 유효 기간
* [BytePlus 이미지 생성 튜토리얼](https://docs.byteplus.com/en/docs/ModelArk/1824121): 모델 비교, 연속 생성, 입력 이미지 제한
* [Seedream 4.0 사용 설명서](https://docs.byteplus.com/en/docs/ModelArk/seedream-4-0-user-manual): BytePlus의 프롬프트 작성 가이드와 예시
* [콘솔의 모델 및 가격](https://api.laozhang.ai/account/pricing): 내 계정에 적용되는 가격


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.