모든 Seedream 요청은 같은 엔드포인트와 JSON 본문 형식을 사용합니다.
- 엔드포인트:
POST https://api.laozhang.ai/v1/images/generations - 이미지 생성: 프롬프트만 보냅니다.
- 이미지 편집·합성:
image에 참조 이미지를 1~10장 넣습니다. - 동시 요청: 플랫폼 차원의 제한이나 스로틀링은 없습니다.
429는 업스트림 용량 때문에 발생하며, 자세한 내용은 동시 요청과 429를 참고하세요.

아래 생성 예제의 출력: Seedream 5.0, 2K. 프롬프트: A beautiful sunset over mountains, realistic style
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은 건당 과금(按次) 모델입니다. 토큰 관리에서 API 키(콘솔에서는 ‘토큰’이라고 부릅니다)를 새로 만들거나 기존 키를 편집해 과금 방식(计费模式)을 사용량 우선(按量优先, 권장) 또는 건당 과금(按次计费)으로 설정합니다. 사용량 우선 키는 사용량 과금 모델도 호출할 수 있고, 건당 과금 키는 건당 과금 모델만 호출할 수 있습니다.키는 서버 측 환경 변수에 보관하세요.

2
환경 설정
키를 환경 변수로 설정하고, Python 예제에서 쓰는
requests를 설치합니다.이미지 생성
워터마크 없는 2K 이미지를 만들고 응답을seedream-generation.json에 저장하는 요청입니다.
data에 이미지가 담겨 옵니다.
결과 저장
응답을 받으면 바로 이미지를 내려받으세요. 아래 스크립트를save_images.py로 저장하면, 응답에 들어 있는 모든 이미지를 url이든 b64_json이든 형식에 관계없이 저장합니다.
save_images.py
저장 완료: seedream-sunset-1.jpg 같은 줄이 출력되면 파일을 열어 결과를 확인하세요.
Python으로 생성하기
이미지 편집
요청에image를 추가하면 기존 이미지를 편집하거나 다시 그립니다. 이 예제는 BytePlus 문서의 공개 샘플 이미지를 쓰므로 그대로 실행할 수 있습니다.
참조 이미지 최대 10장 조합
참조 이미지를 여러 장 쓰려면image를 배열로 보냅니다. 각 항목은 공개 URL이거나 data:image/png;base64,... 같은 data URL입니다. 이미지는 배열 순서대로 번호가 매겨지므로 프롬프트에서 이미지 1, 이미지 2처럼 가리킬 수 있습니다.
다음 예제는 로컬 파일 세 개를 data URL로 보냅니다.
Python으로 참조 이미지 조합하기
아래 함수는 참조 이미지를 1~10장 받아, 로컬 파일은 data URL로 바꾸고 공개 URL은 그대로 전달합니다.이미지를 투명 레이어로 분리
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을 반환합니다.
레이어 요청 보내기
image URL은 공개적으로 내려받을 수 있는 자신의 이미지로 바꾸거나 data URL로 보내세요. 5.0 Pro를 쓰려면 model만 바꾸면 됩니다.
레이어 응답 읽기
data[]의 첫 항목은 배경이고, 나머지 항목은 각각 레이어 하나입니다. 아래 응답은 배경과 레이어 하나만 남기고 줄인 것입니다.
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를 설치하세요.
save_layers.py
layer-00-base.jpg, layer-04-spaceship.png 같은 파일과 recomposited.png가 만들어집니다. 배경을 바꾸거나 요소를 빼려면, 합성하기 전에 배경 파일을 교체하거나 해당 레이어를 건너뛰세요.
파라미터
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배입니다.
size에는 어떤 값을 넣나요? 4K도 되나요?
두 방식 중 하나만 쓰세요. 해상도 단계를 보내고 종횡비는 프롬프트에 적거나(예: “16:9 가로 화면”), 2848x1600처럼 정확한 픽셀을 보냅니다. 모델별 해상도 단계는 다음과 같습니다.
seedream-5-0-flash-260915:1K,1.5K,2K(기본값 2K)seedream-5-0-pro-260628:1K,2Kseedream-5-0-260128:2K,3K(최대 3K)seedream-4-5-251128:2K,4Kseedream-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이고, 참조 이미지는 과금되지 않습니다. 실제 청구 금액은 호출 로그에서 확인하세요.
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
워터마크는 어떻게 없애나요?
이 페이지의 모든 예제처럼"watermark": false를 보내세요. BytePlus는 watermark 기본값이 true이고 오른쪽 아래에 “AI generated” 라벨을 넣으므로, 깨끗한 이미지가 필요하면 false를 명시하세요.
결과 URL은 얼마나 유효한가요? Base64로 받을 수 있나요?
BytePlus에 따르면 이미지 URL은 생성 후 24시간 동안 유효합니다. 응답을 받는 즉시 이미지를 내려받아 사본을 보관하고, 반환된 URL을 영구 주소로 저장하지 마세요. 응답 안에서 이미지를 바로 받으려면response_format을 b64_json으로 설정하세요. save_images.py 스크립트와 Python 예제는 두 형식을 모두 처리합니다.
실패한 요청도 과금되나요?
과금되지 않습니다. 파라미터 오류나 모더레이션 차단처럼 200이 아닌 응답은 과금되지 않으며, 이미지가 반환되었을 때만 요금이 나갑니다. 클라이언트 타임아웃은 실패와 다릅니다. 서버에서는 이미지 생성이 끝나 과금되었을 수 있으니, 다시 보내기 전에 호출 로그를 확인하세요. 실제 청구 내역의 최종 기준은 호출 로그입니다. 아직 처리 중인 요청을 끊지 않도록 모델별로 클라이언트 타임아웃을 설정하세요.- 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 출시 공지: 가격, 이전 시 주의할 점, 버전 비교
- 이미지 API 비교: Seedream과 다른 이미지 모델 비교
- Images API: 공통 요청·응답 형식
- AI 모델 API 가격표: Seedream 현재 가격과 그룹
- 호출 로그: 요청별 모델과 청구 금액 확인
참고 자료
- BytePlus ModelArk 이미지 생성 API: Seedream 공식 요청 파라미터,
size범위, URL 유효 기간 - BytePlus 이미지 생성 튜토리얼: 모델 비교, 연속 생성, 입력 이미지 제한
- Seedream 4.0 사용 설명서: BytePlus의 프롬프트 작성 가이드와 예시
- 콘솔의 모델 및 가격: 내 계정에 적용되는 가격