Seedream 5.5 API 사용법: Python 코드, 가격과 실제 출력

Seedream 5.5 API를 호출하려면 "model": "seedream-5-5"와 프롬프트를 담아 https://api.seedrouter.ai/v1/images/generations 로 POST를 보내고, 반환된 태스크 id를 보관한 뒤 상태가 completed가 될 때까지 GET /v1/tasks/{id}를 폴링하세요. 완료된 태스크에는 이미지 URL이 들어 있습니다. 같은 요청으로 참조 이미지 최대 10장을 사용한 편집, 투명 배경 PNG 생성, 이미지 한 장을 투명 레이어로 분리하는 것도 가능합니다.

ByteDance는 2026년 11월 9일 Seedream 5.5를 출시했습니다. 주요 변화는 여러 차례 편집해도 더 안정적인 결과, 기본 기능으로 지원하는 투명 배경 출력, 더 선명한 작은 글자와 더 사실적인 이미지 세 가지입니다.^[1] 저희는 다음 날 SeedRouter에서 세 번 실행했습니다. 이 튜토리얼에서는 그때 보낸 코드, 반환된 결과, 걸린 시간과 비용을 소개합니다. 모든 필드는 Seedream 5.5 API 레퍼런스에 있으며 Playground는 모델 페이지에서 확인할 수 있습니다.

첫 Seedream 5.5 API 호출 전에 무엇이 필요한가요?

API 키와 모델 ID, 두 가지입니다. 다운로드할 것은 없습니다. ByteDance가 Seedream 5.5의 가중치를 공개하지 않았으므로 모델은 호스팅된 API로 실행되고 코드에서는 JSON만 보냅니다.

API 키 페이지에서 키를 만들고 서버의 환경 변수에 보관하세요. 브라우저 코드에는 절대 넣지 마세요:

export SEEDROUTER_API_KEY="your-key"
pip install requests

모델 ID는 seedream-5-5입니다. 하나의 ID가 텍스트로 이미지 생성, 편집, 레이어 분리를 모두 처리하며 요청 필드에 따라 실행할 기능이 정해집니다. 신규 계정에는 소액의 무료 잔액이 있어 충전 전에 1K 테스트 이미지 몇 장을 만들 수 있습니다.

Python으로 이미지를 생성하려면 어떻게 하나요?

제출하면 이미지가 아닌 태스크가 즉시 반환됩니다. 이 스크립트는 프롬프트를 보내고 10초마다 폴링하다가 15분 뒤 기다리기를 중단하며 반환된 이미지를 각각 저장합니다.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

이것이 첫 번째 실행입니다. 47초 만에 완료됐고 1248 × 832 PNG 한 장을 반환했습니다.

실서비스에서는 이 루프의 두 가지 습관이 중요합니다. 폴링이 타임아웃되면 태스크 ID를 보관하고 다시 확인하세요. 이미지가 아직 생성 중일 수 있습니다. "재시도"한다며 같은 요청을 다시 보내지 마세요. 태스크가 하나 더 생기고 비용도 한 번 더 청구됩니다.

어떤 요청 필드가 중요한가요?

대부분의 요청에는 model, prompt와 size만 필요합니다. 가장 자주 설정하는 필드와 기본값은 다음과 같습니다:

최대 출력은 2K입니다. 저희가 2K로 실행한 16:9 편집은 2560 × 1440으로 반환됐고, 정확한 픽셀 크기는 총 4,624,220픽셀까지 지정할 수 있습니다. 화면비 필드는 없습니다. 고정된 화면 형태에는 정확한 픽셀 크기를 보내세요. 3K나 4K 해상도 단계는 없으므로 더 큰 파일이 필요하면 나중에 확대해야 합니다. API 레퍼런스에는 모든 필드가 나와 있습니다. 여기에 나와 있지 않은 필드는 오류로 거부되지 않고 삭제됩니다. 다른 이미지 API에서 쓰던 seed, style이나 n이 들어가도 요청은 실패하지 않으며 효과도 없습니다. 요청 한 번에 이미지 한 장을 만듭니다.

참조 이미지로 이미지를 편집하려면 어떻게 하나요?

원본을 image에 넣고 프롬프트에 바꿀 부분과 유지할 부분을 설명하세요. 두 번째 실행에서는 등대 상단 회랑에서 페인트를 칠하는 사람의 맑은 날 사진을 겨울밤으로 바꿨습니다:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

40초가 걸렸고 2560 × 1440 PNG를 반환했습니다. 페인트를 칠하는 사람, 그의 자세, 붓, 감아 놓은 밧줄, 페인트 통 두 개와 난간이 모두 제자리를 유지했습니다. 내리는 눈, 회랑 바닥과 어깨에 쌓인 눈, 어두운 하늘과 탑의 빨간 띠 위쪽에서 불이 켜진 창문이 추가됐습니다.

참조 이미지가 여러 장이면 "이미지 2의 재킷"처럼 목록의 순서로 지칭하세요. 첫 장을 포함해 모든 참조 이미지가 과금되므로 편집에 필요한 이미지만 보내세요.

ByteDance가 이 버전에서 내세우는 핵심은 편집을 반복해도 편집하지 않은 영역이 픽셀 수준에서 동일하게 유지된다는 점이며, 연속 100회 편집으로 테스트했다고 합니다.^[1] API로 여러 차례 편집하려면 완료된 태스크에서 URL을 가져와 다음 요청의 image로 전달하는 루프를 만듭니다. 저희는 아직 긴 연속 편집을 직접 실행하지 않아 100회라는 수치는 확인할 수 없습니다. 매번 새 태스크가 생기고 참조 이미지에도 비용이 든다는 점을 기억하세요.

투명 PNG는 어떻게 받나요?

background를 transparent로 설정하고 output_format은 png로 유지하세요. 프롬프트만으로도, 참조 이미지가 있어도 작동합니다:

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

JPEG에는 알파 채널이 없으므로 transparent와 jpeg의 조합은 태스크 생성 전에 거부됩니다. ByteDance는 완전한 투명과 반투명을 지원하고 가장자리를 세심하게 렌더링하는 네이티브 RGBA 출력이라고 설명하며, 별도로 배경을 제거할 필요가 없다고 합니다.^[1]

API로 이미지를 레이어로 분리하려면 어떻게 하나요?

layer_decomposition: true와 함께 이미지를 정확히 한 장 보내세요. 세 번째 실행에서는 문자 인식을 켜고 최대 네 장을 반환하도록 설정해 재즈 포스터를 분리했습니다:

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

39초가 걸렸고 배경 베이스 이미지와 투명 레이어 세 개, 총 네 장을 반환했습니다.

텍스트 레이어 두 개에는 읽어 낸 글자도 포함됐습니다. 제목 레이어의 text_recognition에는 "BLUE TIDE\nSESSIONS"가 담겼고 글꼴은 HTF Didot, 색상은 #122C4D로 추정됐습니다. 행사 안내 문구 레이어에는 "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM"가 담겼습니다. 각 줄에 개별 경계 상자와 스타일이 있으므로 같은 위치에 원하는 글꼴로 다시 입력할 수 있습니다.

결과를 활용하기 전에 알아둘 점이 세 가지 있습니다:

• 레이어 파일은 경계 상자보다 큽니다. 배율은 제목 1.74×, 일러스트 1.08×, 행사 안내 문구 2.59×로 레이어마다 다릅니다. 각 PNG를 bounding_box.absolute의 크기로 줄여 배치한 뒤 z_index 오름차순으로 쌓으세요.
• max_images는 상한이며, 낮게 설정하면 요소들이 합쳐집니다. 네 장으로 설정하자 모델은 색소폰 연주자, 파도와 산호색 태양을 하나의 레이어에 담았습니다. 예상하는 요소 수에 맞춰 여유를 두세요.
• 한 요소가 두 번 나타날 수 있습니다. 산호색 태양은 일러스트 레이어에 들어갔고 배경 베이스 이미지에도 남았습니다. 레이어를 옮기기 전에 배경 베이스 이미지를 확인하세요.

Seedream 5.5 API 비용은 얼마인가요?

각 이미지의 크기에 따라 이미지당 비용을 내며, 모든 참조 이미지 비용이 추가됩니다. 261만 픽셀 이하(1K와 1.5K)는 낮은 요금 단계, 2K 이상은 높은 요금 단계입니다. 레이어 분리는 배경 베이스 이미지와 각 레이어에 각각의 크기로 과금합니다. 실패한 태스크는 과금되지 않습니다.

2026년 11월 10일에 실행한 세 번의 결과와 각각의 과금 대상입니다:

이 수량에 위 표의 가격을 곱하면 청구액이 나옵니다. 주의할 것은 레이어 분리입니다. 배경 베이스 이미지와 각 레이어가 모두 과금되므로 한 장이 아니라 네 장의 비용이 들었습니다.

레이어 분리 중에는 최종 과금액보다 많은 잔액을 예약합니다. 태스크가 접수되면 max_images장분의 잔액이 예약되며, 생략하면 30장이고 auto는 높은 요금 단계로 계산합니다. 태스크가 끝나면 반환된 이미지에 과금하고 나머지는 해제합니다. 따라서 max_images와 size가 모두 없는 분리는 결과가 네 장이어도 시작할 때 높은 요금 단계 30장분과 입력 이미지 비용을 감당할 잔액이 필요합니다. 저희 세 번째 실행(네 장 요청, 네 장 반환)처럼 max_images를 예상 요소 수에 가까운 값으로 설정하고 해상도 단계를 선택하면 예약 금액이 청구액에 가깝게 유지됩니다.

어떤 오류에 대비해야 하나요?

참조 이미지는 공개 HTTP(S) URL이어야 합니다. Base64 data URI는 거부되므로 먼저 파일을 자체 스토리지에 업로드하세요. JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC와 HEIF를 지원하며 각각 최대 30 MB입니다. 전체 코드는 오류 목록에서 확인하세요.

자주 묻는 질문

Seedream 5.5 Pro가 있나요?

아직 없습니다. ByteDance의 출시 글에는 "A Pro version of the Seedream 5.5 series will follow"(이 시리즈의 Pro 버전이 뒤이어 출시됩니다)라고 적혀 있으며 날짜는 제시하지 않았습니다.^[1] 현재 API에는 seedream-5-5 모델 하나가 있습니다. 이전 세대의 Pro 모델도 Seedream 5.0 Pro로 계속 사용할 수 있습니다.

Seedream 5.5 API는 무료인가요?

아니요. 구독 없이 선불 잔액에서 이미지당 비용을 냅니다. 신규 계정의 소액 무료 잔액으로 1K 이미지 몇 장을 만들 수 있어 충전하기 전에 위 스크립트를 실행해 볼 수 있습니다.

Seedream 5.5를 다운로드할 수 있나요?

아니요. ByteDance가 모델 가중치를 공개하지 않았으므로 로컬에서 실행할 파일이 없습니다. 이 API 같은 API를 통해 사용합니다.

참조 이미지는 몇 장까지 보낼 수 있나요?

image에 최대 10장까지 보낼 수 있습니다. 레이어 분리에는 정확히 한 장을 사용합니다.

요청 한 번에 얼마나 걸리나요?

저희 세 번의 실행은 39~47초가 걸렸습니다. 많은 레이어를 반환하는 분리에는 몇 분이 걸릴 수 있어 위 스크립트는 최대 15분까지 폴링합니다.

참고 자료

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. 2026년 11월 9일. 2026년 11월 11일 seed.bytedance.com에서 확인했습니다.
2. SeedRouter. Seedream 5.5 API 레퍼런스. /docs/seedream-5-5.