기능별
동영상
동영상은 항상 작업으로 실행됩니다. 제출한 뒤 다시 조회하거나 콜백을 받으세요. 길고 선명한 클립일수록 비용이 큽니다.
#1. 모델 선택
doubao-seedance-2.0-mini$0.02288 / 요청제한 및 상태
이 용도로 사용할 수 있는 온라인 모델이 13개 있습니다. 모델을 바꾸면 아래 코드도 바뀝니다.
#2. 요청 복사
YOUR_API_KEY를 내 키로 바꾼 뒤 실행하세요. 표시된 옵션은 이 모델이 받는 옵션입니다.
https://www.aisplice.store/v1/videosBearer API key비동기 작업옵션이 모델에 공개된 옵션만 표시됩니다.
# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"
# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/videos \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
-d '{
"model": "Seedance 2.0 Mini",
"prompt": "A cinematic scene with careful composition",
"duration": 5,
"resolution": "720p",
"size": "16:9",
"metadata": {
"generate_audio": true
}
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
printf '%s\n' "$SUBMITTED" >&2
exit 1
fi
echo "task_id=$TASK_ID"
# 2. Poll until terminal
while true; do
STATUS_JSON=$(curl --fail-with-body -sS \
"https://www.aisplice.store/v1/videos/$TASK_ID" \
-H "Authorization: Bearer $API_KEY")
STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
echo "status=$STATUS"
case "$STATUS" in
completed|succeeded|success) break ;;
failed|failure|cancelled|canceled)
printf '%s\n' "$STATUS_JSON" | jq .
exit 1
;;
esac
sleep 5
done
# 3. Fetch the final result
curl --fail-with-body -sS \
"https://www.aisplice.store/v1/videos/$TASK_ID/content" \
-H "Authorization: Bearer $API_KEY" | jq .이 모델에는 공개 미디어 URL이 필요합니다. 먼저 로컬 파일을 업로드한 뒤 모델 요청에 public_url을 넣으세요. 큰 Base64 본문은 피하세요.
업로드 가이드 읽기모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
model이 요청에 사용할 정확한 모델 식별자.
doubao-seedance-2.0-minipromptVideo prompt, up to 4000 characters; 500 or fewer recommended.
durationOutput seconds from 4 to 15.
resolution요청할 출력 해상도.
480p720psizeAspect ratio between 0.5 and 2.5.
16:99:161:14:33:421:9adaptiveimagesUp to 9 public reference-image URLs, or exactly one first-frame image when image_tail is set.
metadata.video_urls공개 HTTP(S) 원본 동영상 URL. 최대 3개.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "video",
"model": "Seedance 2.0 Mini",
"status": "queued"
}대기 중
queued · submitted · in_progress · processing
성공
completed · succeeded · success
실패
failed · failure · cancelled · canceled
#3. 결과 받기
제출 호출은 바로 task_id로 응답합니다. status가 completed가 될 때까지 몇 초마다 작업을 조회하거나, webhook_url을 넘기면 완료 시 저희가 호출해 드립니다.
GET https://www.aisplice.store/v1/videos/{task_id}
GET https://www.aisplice.store/v1/videos/{task_id}/content
길이와 해상도가 요금 구간을 정합니다. 실행 중인 작업은 취소할 수 있습니다. API 레퍼런스를 참고하세요.
성공했을 때만 과금
#문제가 생겼을 때
- 필드 이름과 함께 400: 이 모델이 받지 않는 옵션입니다. 2단계에 나열된 값을 사용하세요.
- 참조 이미지 또는 동영상 거부: 모델이 다운로드할 수 있는 공개 URL이어야 합니다.
- 모델이 콘텐츠를 거부함: 프롬프트를 바꿔 쓰세요. 거부된 요청은 과금되지 않습니다.
- 402: 잔액이 이 요청에 부족합니다. 지갑에서 충전한 뒤 다시 시도하세요.
- 429: 요청 속도를 줄이고 Retry-After 초만큼 기다린 뒤 다시 시도하세요.
- 503 model_not_found: 모델 이름이 틀렸거나 모델이 오프라인입니다. 1단계에서 다시 고르세요.
#첫 프레임·마지막 프레임, 참조 이미지와 동영상
지원하는 모델은 2단계에 첫 프레임, 마지막 프레임, 참조 이미지, 참조 동영상 필드를 표시합니다. 공개 URL을 넣고, 로컬 파일은 먼저 업로드하세요.
제품에 통합하기사용자에게 먼저 보여 줄 옵션과 나중에 추가할 옵션.
사용자에게 먼저 보여 줄 옵션프롬프트와 가격에 영향을 주는 옵션 하나로 시작하고, 기본 흐름이 동작하면 나머지를 추가하세요.+
창작 의도
prompt 같은 필드는 사용자가 무엇이 바뀌는지 바로 이해할 수 있으므로 UI에 두어야 합니다.
비용 배수 항목
duration, resolution, size, count 같은 필드는 가격을 명확히 설명할 수 있을 때만 도입하세요.
모드 전환 항목
image, mask, 후속 작업 ID 같은 필드는 워크플로 자체를 바꾸므로 전용 모드에서만 보여야 합니다.
시스템 연동 항목
webhook_secret 같은 필드는 일반 크리에이터가 아닌 연동 개발자를 위한 것이므로 기본 UI에서 빼 두세요.
prompt- 노출 시점
- 항상 노출합니다. 장면이나 움직임의 방향을 정의합니다.
- 권장 기본값
- UI에서 필수.
- 중요한 이유
- 이것이 없으면 사용자가 클립의 의도를 조정할 수 없습니다.
image / images- 노출 시점
- 참조 기반 또는 이미지→동영상 제품에서만 노출합니다.
- 권장 기본값
- 프롬프트만 쓰는 흐름에서는 숨깁니다.
- 중요한 이유
- 생성 모드를 바꾸므로 의도적인 제품 결정이어야 합니다.
duration- 노출 시점
- 기본 비동기 흐름이 안정되고 가격이 표시된 뒤에 노출합니다.
- 권장 기본값
- 지원되는 가장 짧은 길이부터 시작합니다.
- 중요한 이유
- 동영상 생성에서 비용과 지연 시간을 가장 크게 늘리는 요소 중 하나입니다.
resolution- 노출 시점
- 고객이 720p, 1080p, 4K 출력을 명시적으로 비교할 때 노출합니다.
- 권장 기본값
- 서버 측에서 권장 해상도 하나를 정합니다.
- 중요한 이유
- 해상도가 높을수록 비용, 대기 시간, 실패 가능성이 커집니다.
webhook_url / webhook_secret- 노출 시점
- 일반 최종 사용자가 아닌 백엔드 연동 개발자에게만 노출합니다.
- 권장 기본값
- UI 제품에서는 폴링을 우선 사용합니다.
- 중요한 이유
- 최종 사용자의 창작이 아니라 시스템 연동을 위한 것이므로, 사용자용 컨트롤에 넣지 않습니다.
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content
Phase 2
- one quality or resolution selector
- clear pricing hint
Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuning결과의 기준은 하나로 유지
아직 해결되지 않았나요?
요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.