
Seedance 2.5 Flash API는 Seedance 2.5 API 중 더 빠르고 저렴한 등급으로, PoYo에서는 모델 ID seedance-2.5-flash 하나로 사용합니다. ByteDance는 2026년 11월 12일에 이 모델을 출시했으며, Seedance 2.5 Flash 모델 페이지에서 플레이그라운드와 실시간 가격을 확인할 수 있습니다. 이 가이드는 2026년 11월 16일에 확인한 Seedance 2.5 Flash API 문서의 스키마를 기준으로, 첫 cURL 요청부터 Python 프로덕션 루프까지 안내합니다.
Seedance 2.5 Flash API 한눈에 보기
| 항목 | 값 |
|---|---|
| 제출 엔드포인트 | POST https://api.poyo.ai/api/generate/submit |
| 상태 엔드포인트 | GET https://api.poyo.ai/api/generate/status/{task_id} |
| 인증 헤더 | Authorization: Bearer $POYO_API_KEY |
| 모델 ID | seedance-2.5-flash (페이지 슬러그 seedance-2-5-flash는 모델 ID가 아님) |
| 필수 필드 | prompt, duration |
| 길이 | 정수 초, 4–30 |
| 해상도 | 480p 또는 720p, 기본값 720p |
| 화면비 | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, 기본값 auto |
| 오디오 | generate_audio, 기본값 true |
| 결과 전달 | 비동기 작업: 상태를 폴링하거나 callback_url 설정 |
cURL로 첫 Seedance 2.5 API 요청 보내기
키를 POYO_API_KEY로 export하고, 브라우저 코드가 아닌 서버에 보관하세요. 다음은 5초짜리 480p 텍스트-동영상 요청으로, 92.5크레딧이면 되는 저비용 첫 테스트입니다.
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
제출에 성공하면 code: 200과 함께 task_id, status(제출 직후에는 항상 not_started), created_time을 담은 data 객체가 반환됩니다. 이것은 접수 확인일 뿐 동영상이 아닙니다. task_id를 저장한 다음 조회하세요.
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
상태는 not_started, running, finished, failed 순으로 바뀝니다. 작업이 finished가 되면 동영상 URL은 file_type: "video"인 data.files[].file_url에 있으며, failed라면 data.error_message를 확인하세요. 생성된 파일은 3일 동안 접근할 수 있으므로 자체 스토리지로 복사해 두세요.
Python: 엄격한 기한을 둔 제출과 폴링
상태 문서는 2–5초 간격의 폴링, 429와 5xx에서의 백오프, 그리고 항상 타임아웃을 설정할 것을 권장합니다. 아래 루프는 이 세 가지를 모두 수행하며, 두 번째 제출은 과금되는 두 번째 작업이 되므로 타임아웃 시에도 절대 다시 제출하지 않습니다.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
참고로 2026년 11월 16일 PoYo 테스트에서 4초 480p 클립은 약 2분, 30초 720p 클립은 3분 이내에 처음부터 끝까지 완료되었습니다. 시간은 부하에 따라 달라지므로 15분 기한은 예상치가 아니라 안전 장치입니다.
폴링 생략하기: callback_url 사용
model 옆에 최상위 callback_url을 추가하세요. 작업이 finished 또는 failed가 되면 PoYo는 code/data 래퍼 없이 작업 데이터 객체(task_id, status, files, created_time, error_message)를 본문으로 POST를 보냅니다. 동영상 웹훅 문서에 따르면 다음과 같습니다.
- URL은 공개 HTTPS여야 하고, 최대 2048자이며, 사설 IP는 허용되지 않습니다.
- 30초 이내에 2xx로 응답하세요. 전달에 실패하면 지수 백오프로 최대 5회 재시도됩니다.
X-Webhook-Signature를base64(HMAC-SHA256(task_id + "." + timestamp, key))로 검증하세요.timestamp는X-Webhook-Timestamp에서, 키는GET /api/api-keys/webhook-secret에서 가져옵니다.- 핸들러를 멱등하게 만드세요. 모든 재시도가 실패해도 상태 엔드포인트에는 결과가 남아 있습니다.
세 가지 입력 모드와 JSON 본문
API는 전송한 미디어에 따라 모드를 선택합니다. mode 필드는 없습니다.
| 모드 | 선택 조건 | 화면비 |
|---|---|---|
| 참조-동영상 | reference_image_urls, reference_video_urls, reference_audio_urls 중 하나라도 비어 있지 않음 | 지원되는 모든 값 |
| 이미지-동영상 (첫 프레임/마지막 프레임) | image_urls가 비어 있지 않음 | auto 또는 생략, 출력은 첫 프레임을 따름 |
| 텍스트-동영상 | 미디어 없음 | 지원되는 모든 값 |
image_urls와 참조 필드는 별도의 요청으로 보냅니다. 아래 본문은 문서에 있는 예제입니다.
텍스트-동영상(720p 30초, 프롬프트에 시간별 샷 목록 포함):
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
첫 프레임과 마지막 프레임(URL 하나는 시작을, 두 번째 URL은 끝을 고정):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
참조-동영상(업로드 순서대로 @Image1, @Video1, @Audio1로 파일을 지칭):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
제출 전에 적용할 검증 규칙
이 규칙을 클라이언트 측에서 확인하면 왕복 요청을 줄이고, 일반적인 400보다 명확한 메시지를 사용자에게 보여 줄 수 있습니다.
| 필드 | 규칙 |
|---|---|
prompt | 필수, 비어 있지 않은 문자열 |
duration | 필수 정수, 4–30 |
resolution | 480p 또는 720p만 가능, 1080p는 seedance-2.5 필요 |
aspect_ratio | 7개 값 중 하나, image_urls 사용 시 auto 또는 생략 |
image_urls | URL 1–2개 (첫 프레임, 그다음 마지막 프레임), JPEG, PNG, WebP, 각 최대 30 MB, 참조 필드와 함께 사용 불가 |
reference_image_urls | 최대 10개, JPEG, PNG, WebP, 각 최대 30 MB |
reference_video_urls | 최대 5개, MP4 또는 MOV, 각 2–30초 및 최대 200 MB, 합계 길이 최대 30초 |
reference_audio_urls | 최대 5개, MP3 또는 WAV, 각 2–30초 및 최대 15 MB, 합계 길이 최대 30초, 참조 이미지 또는 동영상 필요 |
| 모든 미디어 URL | 공개 HTTP 또는 HTTPS, 직접 다운로드 가능해야 함 (로그인 페이지나 만료되는 미리보기 불가) |
참조 파일의 합계 길이는 작업 제출 시 검사됩니다. 스키마는 input에 additionalProperties: false도 설정하므로, seed나 negative_prompt 같은 다른 벤더 API의 필드는 보내지 마세요.
처리해야 할 오류
본문의 code 필드를 항상 읽으세요. 제출 엔드포인트의 일부 검증 오류는 HTTP 200과 "code": 400으로 반환됩니다. 오류 코드 레퍼런스에는 다음이 나열되어 있습니다.
| 코드 | 유형 | 대응 |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | 요청이나 미디어를 수정, 그대로 재시도하지 않음 |
401 | authentication_error | Bearer 헤더와 키가 아직 유효한지 확인 |
402 | insufficient_credits_error | 충전 후 다시 제출 |
429 | 속도 제한 | 다시 폴링하거나 제출하기 전에 백오프 (1초, 2초, 4초...) |
500, 502, 503 | 서버 또는 업스트림 | 백오프로 상태 조회를 재시도, 다시 제출하기 전에 상태 확인 |
작업 failed | error_message 설정됨 | 작업 ID를 기록, 실패한 작업은 credits_amount: 0으로 표시 |
첫 청구 금액 계산 방법
참조 동영상이 없으면 비용은 출력 초 수에 초당 요금을 곱한 값입니다. 480p는 18.5크레딧($0.0925), 720p는 41크레딧($0.205)이며, 1크레딧 = $0.005입니다. 생성된 오디오에는 추가 비용이 없습니다.
| 위의 요청 | 과금 초 | 크레딧 | USD |
|---|---|---|---|
| cURL 테스트, 5초 480p | 5 | 92.5 | $0.4625 |
| 텍스트-동영상, 30초 720p | 30 | 1,230 | $6.15 |
| 첫/마지막 프레임, 5초 720p | 5 | 205 | $1.025 |
| 참조 이미지 + 오디오, 6초 480p | 6 | 111 | $0.555 |
reference_video_urls를 하나라도 추가하면 더 낮은 동영상 포함 요금(480p 11.5크레딧, 720p 25.5크레딧)으로 바뀌며, 이는 과금 초에 적용됩니다. 과금 초는 출력 길이에 각 참조 동영상의 길이를 정수 초로 내림해 더한 값입니다. Seedance 2.5 API 가격 분석에서 이런 경우를 계산해 봅니다. 완료된 작업의 청구 금액은 상태 응답의 credits_amount로 표시됩니다.
1080p가 필요하면 Seedance 2.5로 전환
요청 필드가 같으므로, 작업을 Flash에서 표준 Seedance 2.5 모델로 옮기려면 모델 ID만 바꾸면 됩니다.
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
두 가지 세부 사항이 있습니다. seedance-2.5 문서는 resolution을 필수로 명시하므로 항상 보내야 하며, 표준 모델은 이미지 최대 30개, 동영상 10개, 오디오 참조 10개를 허용합니다. 1080p에서는 초당 114크레딧($0.57)입니다. 라우팅 결정은 Seedance 2.5 Flash vs Seedance 2.5를, Seedance 2.5와 다른 벤더 비교는 Kling 4.0 vs Seedance 2.5를 참고하세요.
자주 묻는 질문
Seedance 2.5 Flash API의 모델 ID는 무엇인가요? 점이 들어간 seedance-2.5-flash입니다. 대시가 들어간 seedance-2-5-flash는 모델 페이지 슬러그일 뿐입니다.
Seedance 2.5 Flash API는 1080p를 지원하나요? 아니요. 480p와 720p를 받습니다. 네이티브 1080p가 필요하면 같은 본문에 "model": "seedance-2.5"와 "resolution": "1080p"를 지정해 보내세요.
Seedance 2.5 API에서 오디오를 끄려면 어떻게 하나요? 무음 클립이 필요하면 "generate_audio": false를 설정하세요. 또는 오디오를 켠 채로 "no background music"처럼 프롬프트에서 개별 레이어를 빼도 됩니다.
Seedance 2.5 Flash 요청 하나에 첫 프레임과 참조 이미지를 함께 쓸 수 있나요? 아니요. image_urls와 reference_* 필드는 별도의 요청으로 보내야 합니다.
Seedance 2.5 Flash API 작업은 얼마나 걸리나요? 2026년 11월 16일 PoYo 테스트에서 4초 480p는 약 2분, 30초 720p는 3분 이내에 처음부터 끝까지 완료되었습니다. 요청을 열어 둔 채 기다리지 말고 폴링하거나 콜백을 사용하세요.
Seedance 2.5 Flash 작업이 실패하면 요금이 부과되나요? 아니요. 실패한 작업은 과금되지 않으며, 상태에 credits_amount: 0이 표시됩니다.