

Seedream 5.0 Pro로 이미지 생성하는 방법
APIMart에서 Seedream 5.0 Pro를 호출하는 단계별 가이드: 인증, 요청 필드, 작업 폴링, 결과 읽기, 링크 만료 전 이미지 저장.
Seedream 5.0 Pro는 POST 요청 한 번, API 키 하나, 그리고 후속 단계 하나로 동작합니다. 작업을 제출해 task_id를 받은 다음, 이미지가 완성될 때까지 작업을 확인하면 됩니다. Seedream 5.0 Pro는 비동기 모델이라 첫 응답에는 이미지가 들어 있지 않습니다.
짧게 정리하면:
- 요청 주소는
https://api.apimart.ai/v1/images/generations - 헤더에
Authorization: Bearer YOUR_API_KEY추가 model은seedream-5-0-proprompt와 함께resolution(1K,1.5K,2K)과size(auto또는16:9같은 비율) 지정- 편집하거나 합성할 때는
image_urls에 참조 이미지를 최대 10장 추가 GET /v1/tasks/{task_id}를 5~10초마다 폴링해 상태가completed가 될 때까지 대기- 이미지 링크는 72시간 동안만 유효하므로 결과를 바로 다운로드
가장 기억할 점: 이 모델은 단일 이미지 모델입니다. 요청 한 번에 이미지 한 장만 반환되며, n이 1보다 크면 거부됩니다. APIMart에서 Seedream 5.0 Pro API를 사용해 볼 수 있고, 전체 필드는 API 레퍼런스에서 확인할 수 있습니다.

핵심 요약
- Seedream 5.0 Pro는
https://api.apimart.ai/v1/images/generations로 POST 요청을 보내 호출합니다. 헤더는 Authorization: Bearer YOUR_API_KEY, model은 seedream-5-0-pro입니다. - 출력 등급은 resolution(1K, 1.5K, 2K)으로, 형태는 size(auto, 10가지 비율 중 하나, 또는 정확한 픽셀)로 정합니다. 1.5K는 1K와 가격이 같고, 3K와 4K는 400을 반환합니다.
- 요청마다 이미지는 한 장만 생성됩니다. n이 1보다 큰 요청, 그룹 생성, 스트리밍, 웹 검색은 모두 400으로 거부되며 작업이 생성되지 않습니다.
- 이미지 편집은 image_urls로 참조 이미지를 최대 10장, 공개 URL 또는 Base64 데이터 URI로 보냅니다.
- 첫 응답에는 task_id만 들어 있습니다. 작업 엔드포인트를 5~10초마다 폴링하고, 72시간 안에 이미지를 저장하세요.
빠른 비교
| 항목 | 용도 | 주요 제한 또는 참고 |
|---|---|---|
| 텍스트-투-이미지 | 프롬프트만으로 새 이미지 생성 | 입력 이미지 불필요 |
| 단일 참조 편집 | 이미지 한 장의 배경, 조명, 디테일 변경 | image_urls에 1장 |
| 다중 참조 편집 | 인물, 의상, 장면 합성 | 참조 이미지 최대 10장 |
| 레이어 분해 | 포스터를 편집 가능한 레이어로 분리 | 입력 이미지는 정확히 1장, PNG 레이어 최대 16장 |
| 투명 배경 | 알파를 유지한 채 레이어 편집 | 알파가 있는 입력 이미지 1장, output_format: "png" |
한마디로: 이 가이드는 인증 설정, 요청 본문 작성, 작업 폴링, 그리고 파일을 잃지 않고 결과를 저장하는 방법을 다룹니다.
1. API 액세스와 인증 설정
1.1 APIMart 계정을 만들고 API 키 발급하기

APIMart에 가입한 뒤 대시보드의 API 키 관리 페이지에서 키를 만듭니다. 만든 즉시 복사해서 서버 측 시크릿 매니저나 환경 변수에 저장하세요.
키를 프론트엔드 코드나 공개 저장소에 두면 안 됩니다. 키를 얻은 사람은 누구나 잔액을 사용할 수 있습니다. Node.js에서는 process.env.APIMART_API_KEY로 읽고, 셸에서는 export APIMART_API_KEY="your-key-here"를 사용합니다.
1.2 Base URL과 Bearer 인증 헤더 설정
모든 요청은 Base URL https://api.apimart.ai로 보내며, 다음 두 헤더를 포함합니다:
| 헤더 | 값 |
|---|---|
Authorization | Bearer YOUR_API_KEY |
Content-Type | application/json |
Bearer 뒤에는 공백을 정확히 하나만 둡니다. 토큰이 없거나 형식이 잘못되면 401이 반환됩니다. cURL은 되는데 앱에서는 안 된다면, 대개 앱이 헤더를 만드는 방식에 문제가 있습니다.
2. Seedream 5.0 Pro 이미지 요청 만들기

2.1 핵심 필드: Model, Prompt, Resolution, Size
텍스트-투-이미지 요청에는 model과 prompt가 필요합니다. 다음 두 필드로 출력을 제어합니다:
model:seedream-5-0-pro(seedream-5.0-pro도 허용).prompt: 자연어 설명. 중국어와 영어 외에도 한국어, 일본어, 스페인어, 포르투갈어, 프랑스어, 독일어, 러시아어, 인도네시아어, 베트남어 등 여러 언어의 텍스트를 네이티브로 렌더링합니다. 영어 기준 약 600단어 이내로 유지하세요. 너무 길면 디테일이 사라질 수 있습니다.resolution:1K(기본값),1.5K,2K. 1.5K는 1K와 가격이 같아서 보통 더 나은 선택입니다.size:auto(기본값), 10가지 비율(1:1,4:3,3:4,16:9,9:16,3:2,2:3,2:1,1:2,21:9) 중 하나, 또는2048x1024같은 정확한 픽셀. 정확한 픽셀은 총 921,6004,624,220이어야 하고, 가로세로 비율은 1:1616:1 사이여야 합니다.
예를 들어 resolution: "1.5K"와 size: "16:9"를 함께 쓰면 2048×1152 이미지가 반환됩니다.
2.2 선택 필드
| 선택 파라미터 | 타입 | 사용 시점 |
|---|---|---|
image_urls | Array | 이미지 편집과 다중 참조 합성. 공개 URL 또는 Base64 데이터 URI 최대 10개 |
output_format | String | jpeg(기본값) 또는 png |
background | String | 원래 알파 채널이 있는 이미지 한 장을 편집할 때 transparent로 투명도 유지(png 필요) |
layer_decomposition | Boolean | 이미지 한 장을 베이스 이미지와 최대 16장의 투명 PNG 레이어로 분리 |
optimize_prompt_options | Object | 프롬프트 최적화. {"mode": "standard"}만 지원 |
watermark | Boolean | 오른쪽 아래에 “AI 생성” 표시 추가 |
nsfw_check | Boolean | 작업 제출 전에 프롬프트와 입력 이미지 검수 |
참조 이미지는 jpeg, png, webp, bmp, tiff, gif, heic, heif를 지원하며, 장당 최대 30 MB, 3,600만 픽셀입니다. 첫 번째 참조 이미지는 무료이고, 두 번째부터는 장마다 고정 추가 요금이 붙습니다.
편집 위치를 정확히 지정하려면 프롬프트에 좌표를 넣으세요. 한 점은 <point>x y</point>, 영역은 <bbox>x1 y1 x2 y2</bbox>입니다.
2.3 이 모델이 거부하는 필드
Seedream 5.0 Pro는 단일 이미지 모델입니다. 다음 요청은 400을 반환하고, 작업이 생성되지 않으며, 요금도 부과되지 않습니다:
n이 1보다 크거나sequential_image_generation사용(그룹 이미지는 Seedream 5.0 Lite 사용)stream또는tools(스트리밍과 웹 검색 미지원)image_urls가 10장 초과3K,4K같은 미지원 등급, 또는 위 목록에 없는 비율
2.4 cURL과 JavaScript 호출 예시
1.5K 등급으로 16:9 이미지 한 장을 생성하는 최소 cURL 요청입니다:
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header "Authorization: Bearer $APIMART_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "seedream-5-0-pro",
"prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
"resolution": "1.5K",
"size": "16:9"
}'
응답은 작업 접수만 확인해 줍니다:
{
"code": 200,
"data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}
Node.js fetch로 다중 참조 편집을 하는 예시입니다:
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.APIMART_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "seedream-5-0-pro",
prompt: "Replace the outfit in image 1 with the outfit in image 2",
image_urls: ["https://example.com/person.jpg", "https://example.com/dress.jpg"],
resolution: "2K",
size: "auto",
}),
});
const { data } = await response.json();
const taskId = data[0].task_id;
이 호출들은 서버에서만 실행하고, 클라이언트 코드에 넣지 마세요.
3. 작업을 폴링하고 이미지 저장하기
3.1 작업 상태 확인
같은 Authorization 헤더를 붙여 GET https://api.apimart.ai/v1/tasks/{task_id}를 보냅니다. Seedream 5.0 Pro는 품질 우선이라 작업에 몇 분이 걸릴 수 있습니다. 5~10초마다 폴링하고, 클라이언트 타임아웃은 약 5분으로 설정하세요.
status가 completed 또는 failed가 되면 폴링을 멈춥니다. 실패한 작업은 전액 환불됩니다.
3.2 결과 읽기
완료된 작업은 다음과 같습니다:
{
"code": 200,
"data": {
"id": "task_01JFXYZ123456789ABCDEF",
"status": "completed",
"progress": 100,
"result": {
"images": [
{
"url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
"expires_at": 1784696685
}
]
}
}
}
이미지는 data.result.images[0].url[0]에서 읽습니다. 응답에는 작업의 cost도 포함됩니다. 링크는 72시간 동안 유효하므로(expires_at은 Unix 타임스탬프), URL만 저장하지 말고 파일을 다운로드해 자체 스토리지로 옮기세요.
3.3 Python 전체 예시
import os
import time
import requests
BASE_URL = "https://api.apimart.ai"
headers = {
"Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
"Content-Type": "application/json",
}
created = requests.post(
f"{BASE_URL}/v1/images/generations",
headers=headers,
json={
"model": "seedream-5-0-pro",
"prompt": "A product poster with the headline SUMMER SALE in bold letters",
"resolution": "1.5K",
"size": "3:4",
"output_format": "png",
},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"][0]["task_id"]
while True:
task = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers, timeout=30).json()["data"]
if task["status"] == "completed":
image_url = task["result"]["images"][0]["url"][0]
break
if task["status"] == "failed":
raise RuntimeError(task.get("error", {}).get("message", task["status"]))
time.sleep(5)
with open("seedream-5-0-pro.png", "wb") as f:
f.write(requests.get(image_url, timeout=60).content)
4. 자주 쓰는 세 가지 이미지 워크플로
-
텍스트가 들어간 포스터와 그래픽. 넣을 문구를 프롬프트 안에 따옴표로 적고, 레이아웃(예: “세로형 포스터, 제목은 상단”)을 설명한 뒤
resolution: "1.5K"와3:4같은 고정 비율을 사용합니다. 2K 등급은 가격이 더 높으므로 최종 결과물에만 사용하세요. -
다중 참조 편집. 인물, 상품, 장면 이미지를
image_urls에 넣고 프롬프트에서는 순서대로 부릅니다(“이미지 1”, “이미지 2”).size: "auto"를 쓰면 출력 비율이 참조 이미지를 따릅니다.<bbox>좌표를 더하면 배치 위치를 정확히 지정할 수 있습니다. -
레이어 분해와 투명 편집. PNG 또는 JPEG 한 장을
layer_decomposition: true와 함께 보내면, 베이스 이미지와 위치·쌓임 순서 정보가 담긴 투명 PNG 레이어를 최대 16장 받습니다. 레이어 하나만 편집하려면 해당 레이어를background: "transparent",output_format: "png"와 함께 다시 보냅니다. 레이어 작업은 먼저 금액을 가승인한 뒤 실제 출력 장수로 정산되며, 초과분은 자동 환불됩니다.
5. Seedream 5.0 Pro를 안정적으로 연동하기 위한 최종 체크리스트
인증과 키 보안. 키는 환경 변수나 시크릿 매니저에 두고, API는 백엔드에서만 호출합니다.
보내기 전에 파라미터 검증. seedream-5-0-pro를 쓰고, n은 생략(또는 1), image_urls는 10장 이하, 1K·1.5K·2K만 지원되는 size와 함께 사용합니다.
비동기 흐름을 전제로 설계. 5~10초마다 폴링하고, 클라이언트 타임아웃은 약 5분, failed 상태도 처리합니다.
전달은 스토리지 문제로 다루기. 작업이 성공하면 즉시 각 이미지를 다운로드하세요. 링크는 72시간 뒤 만료됩니다.
확장 전에 비용 확인. 출력은 픽셀 등급별로 장당 과금되며(1K와 1.5K는 같은 낮은 가격, 2K는 더 비쌈), 두 번째부터의 참조 이미지에는 추가 요금이 붙습니다. 대량 실행 전에 실시간 가격표를 확인하세요.
자주 묻는 질문
task_id를 받은 뒤 이미지 작업은 어떻게 확인하나요?
Authorization: Bearer 헤더를 붙여 GET https://api.apimart.ai/v1/tasks/{task_id}를 보냅니다.
5~10초마다 폴링해 status가 completed가 되면 data.result.images[0].url[0]에서 이미지를 읽습니다. 상태가 failed이면 error 필드를 확인하세요. 실패한 작업은 환불됩니다.
요청 한 번으로 여러 장의 이미지나 Base64 출력을 받을 수 있나요?
아니요. Seedream 5.0 Pro는 요청당 이미지 한 장을 반환하며, n이 1보다 크면 400이 반환됩니다. 여러 변형이 필요하면 요청을 여러 번 보내거나, 그룹 생성을 지원하는 Seedream 5.0 Lite를 사용하세요.
결과는 항상 URL이며, output_format으로 jpeg 또는 png를 고를 수 있습니다. Base64는 image_urls의 입력 이미지에만 지원되고, 출력에는 지원되지 않습니다.
생성한 이미지를 잃지 않으려면 어떻게 해야 하나요?
이미지 링크는 72시간 동안 유효하며, 결과의 expires_at으로 정확한 만료 시점을 알 수 있습니다.
작업이 completed가 되는 즉시 각 이미지를 자체 스토리지로 다운로드하고, task_id도 직접 기록해 두세요. 반환된 URL을 영구 저장소로 취급하지 마세요.
APIMart 팀 소개
APIMart 팀은 AI로 제품을 만드는 개발자를 위해 모델 가이드, 비교 분석, 가격 분석을 작성합니다. APIMart는 하나의 API로 여러 제공업체의 채팅·이미지·영상 모델을 제공하므로, 이 글에서 다룬 모델을 출시 전에 나란히 비교해 볼 수 있습니다.
모델 마켓에서 원하는 모델을 선택하세요
APIMart 모델 마켓에서 채팅, 이미지, 비디오 모델을 사용해 보고 하나의 통합 API로 모델 기능을 빠르게 경험하세요.
