기능별

동영상

동영상은 항상 작업으로 실행됩니다. 제출한 뒤 다시 조회하거나 콜백을 받으세요. 길고 선명한 클립일수록 비용이 큽니다.

#1. 모델 선택

doubao-seedance-2.5$0.216 / 요청제한 및 상태

이 용도로 사용할 수 있는 온라인 모델이 13개 있습니다. 모델을 바꾸면 아래 코드도 바뀝니다.

#2. 요청 복사

YOUR_API_KEY를 내 키로 바꾼 뒤 실행하세요. 표시된 옵션은 이 모델이 받는 옵션입니다.

POSThttps://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.5",
  "prompt": "A cinematic scene with careful composition",
  "nsfw_check": false,
  "duration": 5,
  "resolution": "720p",
  "metadata": {
    "generate_audio": true,
    "watermark": false,
    "output_format": "mp4",
    "return_last_frame": false
  },
  "size": "1:1"
}')
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
string필수

이 요청에 사용할 정확한 모델 식별자.

doubao-seedance-2.5
prompt
string필수

원하는 결과를 설명하는 지시문.

duration
integer선택

Output seconds; -1 lets Seedance choose automatically.

-1456789101112131415161718192021222324252627282930
resolution
string선택

요청할 출력 해상도.

480p720p1080p
size
string선택

First/last-frame and edit modes require adaptive.

adaptive21:916:94:31:13:49:16
images
string[]선택

Up to 30 image references. Use image_tail with exactly one first-frame image for first/last-frame mode.

metadata.video_urls
string[]선택

공개 HTTP(S) 원본 동영상 URL. 최대 10개.

응답 흐름

작업 상태, 최종 상태, 결과 응답 예시.

제출
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "Seedance 2.5",
  "status": "queued"
}

대기 중

queued · submitted · in_progress · processing

성공

completed · succeeded · success

실패

failed · failure · cancelled · canceled

모든 필드: API 레퍼런스의 /v1/videos →

#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 제품에서는 폴링을 우선 사용합니다.
    중요한 이유
    최종 사용자의 창작이 아니라 시스템 연동을 위한 것이므로, 사용자용 컨트롤에 넣지 않습니다.
recommended-rollout.txt
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

결과의 기준은 하나로 유지

작업이 끝나면 /content가 반환하는 플랫폼 URL을 기준으로 앱을 통일하세요. 업스트림 제공업체의 세부 정보를 숨기고 과거 결과도 안정적으로 재생할 수 있습니다.

아직 해결되지 않았나요?

요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.