이미지 생성 · 영상 생성 · 인증 구조 · Endpoint 설정
Seedream / SeedEdit / Seedance 모델 전체 연동 가이드
ModelArk는 두 종류의 API를 제공합니다
이미지·영상 생성 실행 API.
인증: Authorization: Bearer <API Key>
Base URL
https://ark.ap-southeast.bytepluses.com/api/v3
사용량 조회(GetUsage), Endpoint 관리 등 운영 API.
인증: AK / SK HMAC-SHA256 서명
Host
ark.ap-southeast-1.byteplusapi.com
이미지 생성(동기) vs 영상 생성(비동기)
이미지·영상 생성 요청 시 모든 호출에 포함
# 모든 Inference 요청 공통 헤더 Authorization: Bearer ark-xxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json
GetUsage, ListEndpoints 등 운영 API 호출 시 사용
Authorization: HMAC-SHA256 Credential={AK}/{date}/{region}/ark/request, SignedHeaders=host;x-content-sha256;x-date, Signature={HMAC-SHA256 서명값} X-Date: 20260617T090000Z X-Content-Sha256: {SHA256(request body)}
| 용도 | 인증 방식 | 키 종류 | 적용 API |
|---|---|---|---|
| 이미지·영상 생성 | Bearer Token | ark-xxx... | POST /images/generations, POST/GET /contents/generations/tasks |
| 사용량·Endpoint 조회 | AK/SK 서명 | AKLT... / SK... | GetUsage, GetEndpoint, ListEndpoints |
모델과 Concurrency를 묶은 배포 단위
| 1 | BytePlus 콘솔 → ModelArk 접속 |
| 2 | Endpoint 관리 → 모델 선택 |
| 3 | Concurrency / RPM 설정 |
| 4 | Endpoint ID 발급 → ep-xxx... |
| 5 | API Key 발급 → ark-xxx... |
API 호출 시 "model" 필드에 Endpoint ID를 입력합니다.
// model 필드 = Endpoint ID { "model": "ep-20260602093311-xxxxx", "prompt": "..." }
| 용도 | 예시 Endpoint ID | 모델 |
|---|---|---|
| 이미지 생성 | ep-img-xxx | Seedream 5.0 Lite |
| 이미지 편집 | ep-edit-xxx | SeedEdit 3.0 |
| 영상 생성 Fast | ep-vid-f-xxx | Seedance 2.0 Fast |
| 영상 생성 Std | ep-vid-s-xxx | Seedance 2.0 |
Concurrency 한도 초과 시 BytePlus는 429 Too Many Requests를 반환합니다.
| 호출 유형 | 권장 처리 |
|---|---|
| 이미지 생성 | Exponential Backoff 재시도 (1s → 2s → 4s) |
| 영상 생성 | 60초 후 재제출 (Task 재큐잉) |
{
"model": "ep-20260602093311-xxxxx", ← Endpoint ID
"prompt": "A luxury perfume bottle on marble,
studio lighting, editorial photography",
"negative_prompt": "blurry, watermark, low quality",
"size": "1024x1024",
"n": 1, ← 최대 4장
"response_format": "url",
"seed": 42, ← 재현성 고정 (선택)
"watermark": false,
"image": "https://..." ← i2i 시 참조 이미지
}
{
"id": "img-20260617-abc123",
"created": 1750147200,
"data": [
{
"url": "https://cdn.byteplus.com/...result.png",
"revised_prompt": "A luxury perfume bottle..."
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0
}
}
{
"model": "ep-20260602093311-yyyyy",
"content": [
{
"type": "text",
"text": "A cinematic drone shot over
the Han River at sunset, 4K"
}
],
"parameters": {
"duration": 5, ← 5 또는 10 (초)
"resolution": "1080p", ← "720p"|"1080p"|"2k"
"ratio": "16:9", ← "16:9"|"9:16"|"1:1"
"generate_audio": false,
"watermark": false,
"seed": 0
}
}
{
"id": "t2v-20260617T093100-xxxxx",
"status": "queued",
"created_at": 1750147200,
"model": "ep-20260602093311-yyyyy"
}
| 파라미터 | 값 | 설명 |
|---|---|---|
| duration | 5, 10 | 영상 길이 (초) |
| resolution | "720p" | "1080p" | "2k" | 출력 해상도 |
| ratio | "16:9" | "9:16" | "1:1" | 종횡비 |
| generate_audio | true / false | 오디오 자동 생성 (1.5 Pro) |
| watermark | true / false | 워터마크 삽입 여부 |
content 배열에 image_url 타입을 먼저 추가
{
"model": "ep-20260602093311-yyyyy",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://cdn.example.com/product.jpg"
}
},
{
"type": "text",
"text": "Animate this product smoothly,
soft lighting, 4K cinematic"
}
],
"parameters": {
"duration": 5,
"resolution": "1080p",
"ratio": "16:9",
"generate_audio": false,
"watermark": false
}
}
BytePlus I2V 권장 사항
| 항목 | 권장값 |
|---|---|
| 포맷 | JPEG, PNG, WebP |
| 최소 해상도 | 300 × 300 px |
| 권장 해상도 | 1280 × 720 이상 |
| 종횡비 | 출력 ratio와 맞추면 크롭 없음 |
| 파일 크기 | 10 MB 이하 |
| 입력 방식 | 공개 URL 또는 Base64 data URL |
"image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ..." }
# queued — 대기 중 { "id": "t2v-xxx", "status": "queued" } # running — 처리 중 { "id": "t2v-xxx", "status": "running" } # succeeded — 완료 { "id": "t2v-20260617T093100-xxxxx", "status": "succeeded", "content": [ { "type": "video_url", "video_url": { "url": "https://cdn.byteplus.com/...result.mp4" } } ] } # failed — 실패 { "id": "t2v-xxx", "status": "failed", "error": { "message": "Content policy violation" } }
| status | 의미 | 다음 액션 |
|---|---|---|
| queued | BytePlus 큐 대기 중 | 계속 폴링 |
| running | 영상 생성 중 | 계속 폴링 |
| succeeded | 완료 — URL 유효 | content[].video_url.url 저장 |
| failed | 실패 | error.message 확인 후 재시도 |
| 해상도 / 길이 | 예상 처리 시간 | 폴링 간격 |
|---|---|---|
| 720p / 5초 | 20 ~ 60초 | 5초 간격 |
| 1080p / 5초 | 40 ~ 90초 | 8초 간격 |
| 1080p / 10초 | 60 ~ 180초 | 10초 간격 |
| Status | 의미 | 대응 |
|---|---|---|
| 400 | 요청 파라미터 오류 | error.message 확인 |
| 401 | API Key 인증 실패 | Bearer 헤더 / Key 확인 |
| 403 | 권한 없음 | Endpoint 접근 권한 확인 |
| 404 | Endpoint / Task 없음 | ID 확인 |
| 429 | Concurrency 한도 초과 | Backoff 후 재시도 |
| 500 | BytePlus 내부 오류 | 잠시 후 재시도 |
{
"error": {
"code": "InvalidParameter",
"message": "model field is required",
"param": "model",
"type": "invalid_request_error"
}
}
| 문서 | URL |
|---|---|
| 🔑 Base URL & Authentication | docs.byteplus.com/.../1298459 |
| 🗝️ API Key 발급 & 설정 | docs.byteplus.com/.../1541594 |
| 🖼️ 이미지 생성 API | docs.byteplus.com/.../1541523 |
| 🎬 영상 생성 Task 생성 | docs.byteplus.com/.../1520757 |
| 🔍 영상 Task 상태 조회 | docs.byteplus.com/.../1521309 |
| 📖 Seedance 2.0 튜토리얼 | docs.byteplus.com/.../2291680 |
추가 문의는 기술 담당자에게 연락 주세요