Seedance 2.5 Flash API 사용법: 비동기 작업, 제한, 오류

AIHubMix8분 분량
Seedance 2.5 Flash API 사용법: 비동기 작업, 제한, 오류

doubao-seedance-2-5-flash를 POST /ai/v1/videos와 함께 사용해 작업을 생성하고, 상태를 조회한 다음 결과를 다운로드하세요. 현재 AIHubMix 스키마는 480p/720p 출력, 4~30초 클립, 이미지 참조 최대 10개, 비디오 참조 최대 5개, 오디오 참조 최대 5개를 지원합니다. /v1/videos를 사용하는 이전 클라이언트는 모델 ID와 함께 엔드포인트도 변경해야 합니다.

이 가이드는 2026년 11월 16일에 확인했습니다. 위의 짧은 ID와 doubao-seedance-2-5-flash-261115 모두 모델 스키마를 반환했고, 1080p 요청은 400 schema_violation 오류로 거부됐습니다. 별도로 시도한 4초 480p 생성 요청은 402 insufficient_quota 오류를 반환했으며, 비디오는 생성되지 않았습니다. 아래 워크플로는 현재 스키마와 문서를 따르지만, 이번 확인에서는 생성 성공, 지연 시간, MOV 출력, 편집을 처음부터 끝까지 검증하지 못했습니다.

사전 준비 및 스키마 확인

Seedance 2.5 Flash 모델 페이지에는 이 가이드 전반에서 사용하는 짧은 ID로 모델이 표시되어 있습니다. 작업을 제출하기 전에 다음을 확인하세요.

  1. AIHubMix 콘솔에서 비동기 미디어 작업을 활성화하세요. 이 기능이 활성화되지 않은 계정에서 발생하는 오류는 문서에 403 async_not_enabled로 기재되어 있습니다.
  2. API 키에 접근 권한이 있고 계정에 잔액이 충분한지 확인하세요. 실제 확인에서는 다음 메시지와 함께 402 insufficient_quota 오류가 반환됐습니다. Your account has insufficient quota. Add credits and try again.
  3. 셸에서 AIHUBMIX_API_KEY를 내보내세요. 키를 소스 파일이나 브라우저 코드에 넣지 마세요.
  4. 현재 스키마를 가져오세요. 스키마 확인 요청에는 인증이 필요하지 않습니다.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

11월 16일 스키마에는 Flash용 경로로 /ai/v1/videos만 나와 있습니다. resolution 값은 480p와 720p를 지원하며, 기본값은 720p입니다. duration에는 4~30 사이의 정수를 입력하거나 모델이 길이를 선택하도록 -1을 지정할 수 있습니다. 비용을 예측 가능하게 관리하려면 길이를 명시하세요.

생성, 상태 조회, 다운로드

AIHubMix 비디오 생성 API는 생성, 상태 조회, 다운로드를 각각 별도의 단계로 처리합니다. 생성 요청의 HTTP 성공 응답은 작업이 접수됐다는 뜻일 뿐이며, 완료 여부는 status: "completed"로 확인해야 합니다. 조회 요청이 HTTP 200을 반환하더라도 작업 자체의 status: "failed"일 수 있습니다.

텍스트-비디오 작업 제출

이 예시는 오디오가 포함된 10초 길이의 720p 16:9 제품 클립을 요청합니다. 텍스트만 사용하므로 외부에 호스팅된 참조 이미지에 의존하지 않습니다.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

반환된 작업 id를 즉시 저장하세요. GET /ai/v1/videos/{id}를 15초마다 호출해 completed, failed 또는 cancelled 상태가 될 때까지 확인하세요. 작업 진행 중에는 비디오 상세 경로를 사용해 상태를 조회하세요. 이 경로는 공급자 상태를 새로 고치며, 통합 작업 목록은 이를 대체할 수 없습니다. 작업이 완료되면 동일한 Bearer 헤더를 사용해 GET /ai/v1/videos/{id}/content로 다운로드하세요.

완전한 Python 클라이언트

python3 -m pip install requests로 종속성을 설치하고, 다음 코드를 seedance_flash.py로 저장한 다음 API 키가 설정된 셸에서 python3 seedance_flash.py를 실행하세요. 이 예시는 문서에 기재된 흐름을 구현합니다. 위에서 설명했듯 할당량 오류로 전체 생성 테스트를 완료하지 못했습니다.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

20분 제한은 클라이언트 측 대기 시간 한도이지, 서버에서 작업을 취소하는 설정도 생성 시간 보장도 아닙니다. 상태 조회나 다운로드에 실패하면 작업 ID를 보관하고 해당 작업을 재시도하세요. 시간 초과가 발생하거나 공급자 상태가 불확실하더라도 생성 요청을 자동으로 다시 제출하지 마세요.

BytePlus의 공식 온라인 추론 요금 기준으로 Flash는 비디오 입력이 없을 때 토큰 100만 개당 $7.00, 비디오 입력이 있을 때 480p/720p 기준 토큰 100만 개당 $4.30입니다. 텍스트만 사용하는 예시의 추정치는 10 × 1280 × 720 × 24 / 1024 = 216,000 토큰입니다. 따라서 720p에서 Flash는 $1.51, 플래그십 2.5는 $2.31입니다. 이는 BytePlus 요금으로 계산한 추정치이며, 실제 AIHubMix 청구 금액을 측정한 값은 아닙니다.

참조 및 웹훅

미디어를 바탕으로 클립을 생성하려면 input_references 항목에 type(image_url, video_url 또는 audio_url)과 접근 가능한 미디어를 가리키는 url을 지정하세요. 스키마에서 각 유형은 10 / 5 / 5개로 제한됩니다. 첫 프레임과 마지막 프레임을 지정하려면 대신 frame_images를 사용하세요. 각 항목에는 frame_type과 중첩된 image_url.url이 필요합니다. frame_images와 input_references를 둘 다 비어 있지 않은 상태로 함께 사용하지 마세요. 프레임 워크플로에는 aspect_ratio: "adaptive"가 필요하며, 마지막 프레임을 지정하려면 첫 프레임도 지정해야 합니다.

비동기 작업 문서에는 webhook_url을 통한 HTTPS 콜백이 설명되어 있습니다. 현재 Flash 스키마에는 이 필드가 있지만 webhook_events_filter는 없고 additionalProperties: false로 설정되어 있으므로, 이 모델 스키마를 따를 때 필터는 생략하세요. 문서에 따르면 기본적으로 completed, failed, cancelled 이벤트가 전송됩니다. 전달은 최소 1회 보장되며 최대 6회 시도하고, 재시도 간격은 1, 4, 16, 64, 256초입니다. event_id를 기준으로 중복을 제거하세요. 작업 수준 콜백에는 별도의 서명 키가 없으므로 작업을 조회해 최종 상태를 확인하세요. 서명 검증이 필요한 애플리케이션을 위한 계정 수준 구독은 문서에 별도로 설명되어 있습니다.

오류: 측정된 내용과 문서에 설명된 내용

1080p: 스키마 거부를 직접 확인한 결과

AIHubMix 모델 ID 두 가지 모두 resolution: "1080p"로 4초 길이를 요청했을 때 HTTP 400을 반환했습니다. 반환된 오류 필드는 다음과 같습니다.

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

응답에는 요청 추적 ID도 포함되어 있었지만 여기서는 생략했습니다. 이는 게이트웨이에서 실제로 확인한 거부 응답이며, 업스트림 오류를 추정한 것이 아닙니다. 이 결과만으로는 생성 성공이나 속도를 확인할 수 없습니다.

아래의 다른 제약 사항은 현재 Flash 스키마에 따른 내용입니다. 이러한 잘못된 조합은 실제 확인 과정에서 각각 따로 제출해 보지 않았습니다.

입력 문제 스키마 요구 사항 해결 방법
4K 출력 480p 또는 720p 해상도 낮추기
참조 수 초과 이미지 10개 / 비디오 5개 / 오디오 5개 개수 줄이기
참조 배열 두 개 비어 있지 않은 배열 하나 워크플로 하나 선택
마지막 프레임만 지정 첫 프레임도 필요 두 프레임 모두 지정
프레임을 사용할 때 고정 비율 지정 적응형 비율 적응형 사용

실존 인물 참조: 검증된 에셋 사용

AIHubMix 문서에 따르면 Doubao가 실존 인물 이미지에 대한 특정 개인정보 보호 거부를 반환하면 doubao_real_person_required 오류가 발생합니다. 이번 확인에서는 이 오류가 발생하지 않았습니다. 문서에 기재된 메시지는 다음과 같습니다.

이 요청에는 실존 인물 이미지가 포함되어 있습니다. 실존 인물 인증을 완료하고 활성 에셋 참조를 사용하세요. https://docs.aihubmix.com/cn/api/doubao-real-person-assets를 참조하세요.

Doubao 실존 인물 에셋 가이드를 따르세요. /ai/v1/asset-groups에서 그룹을 만들고, /ai/v1/asset-groups/{id}/verification-sessions에서 인증 세션을 만든 다음, 이미지에 등장하는 사람이 웹 인증을 완료하도록 하세요. 이후 /ai/v1/asset-groups/{id}/assets에서 에셋을 등록하고 활성 상태가 될 때까지 기다립니다. 생성 참조에는 asset://<ASSET_ID>를 사용하세요. 사진의 원본 URL은 동의 및 에셋 등록 절차를 대신할 수 없습니다.

할당량, 요청 크기, 다운로드

실제로 확인된 402 insufficient_quota 오류로 인해 유효한 해상도 설정을 사용한 요청도 생성 단계에 도달하지 못했습니다. 다시 시도하기 전에 잔액을 충전하세요. 프롬프트나 모델 ID가 올바른데도 이 응답이 발생한다면, 이를 변경해도 해결되지 않습니다. 403 async_not_enabled는 이와 다른 사전 요건 오류로, 콘솔에서 기능을 활성화해야 합니다.

AIHubMix 문서에 따르면 요청 본문 크기는 32 MiB로 제한되며, 제한을 초과하면 413 request_too_large 오류가 발생합니다. 공개 URL을 사용하면 Base64 확장으로 요청 본문이 커지는 문제를 피할 수 있습니다. 다만 참조 미디어는 모델 자체의 크기 및 형식 제한을 충족해야 합니다.

비디오가 완료되면 신속히 저장하세요. 기존 Seedance 2.5 통합 가이드에서는 출력 URL의 유효 기간이 약 30분으로 짧다고 안내합니다. Flash의 고정 보관 기간은 여기서 확인하지 못했습니다. 비디오 API는 expires_at: null을 반환할 수 있지만, 이것이 무기한 보관을 보장하지는 않습니다. 문서에 기재된 다운로드 오류로는 410 artifact_expired와 429 too_many_downloads가 있습니다. 다운로드 중 일시적인 서비스 오류가 발생하면 클립을 다시 생성하지 말고 기존 작업에서 다운로드를 재시도하세요.

요청이 유효해도 발생할 수 있는 마이그레이션 함정

Volcengine Seedance 2.5 가이드에는 Flash가 해당 모델 계열에 명시적으로 포함되어 있고 MOV 출력, 편집, 확장 기능도 확인되어 있습니다. 하지만 공급업체가 설명하는 이러한 기능과 게이트웨이를 통해 검증된 기능은 구분해야 합니다.

  • MOV 및 편집 필드는 제공되지만, 여기서는 처음부터 끝까지 테스트하지 않았습니다. Flash 스키마는 extra.output_format: "mp4" 또는 "mov"와 extra.omni_reference_task_type 값인 auto, reference, edit, extend를 지원합니다. 작업 유형 필드를 명시적으로 전송하면 스키마에서 비어 있지 않은 input_references를 요구합니다. edit에는 비디오 참조, 적응형 비율, duration: -1도 필요하고, extend에는 비디오 참조와 적응형 비율이 필요합니다.
  • 작업 유형을 명시해도 모델이 이에 동의한다는 보장은 없습니다. Ark 문서에는 추론된 작업 유형과 매개변수가 충돌할 때 비동기 InvalidParameter.TaskTypeConstraint 오류가, 추론된 유형이 명시적으로 요청한 유형과 다를 때 InvalidParameter.TaskTypeMismatch 오류가 발생한다고 나와 있습니다. AIHubMix에서 이에 대응하는 정확한 오류 매핑은 측정하지 못했습니다. 게이트웨이 오류 코드를 미리 단정하지 말고 반환된 작업의 error를 확인하세요.
  • Flash에는 Draft 승격 기능이 없습니다. 공급업체는 2단계 480p Draft에서 최종 출력으로 이어지는 워크플로를 플래그십 2.5로 제한합니다. Flash는 이를 지원하지 않으며, 현재 AIHubMix의 두 모델 스키마 모두 draft와 draft_task를 포함하지 않습니다.
  • 비디오 입력은 요금에 영향을 줍니다. 공식 요금은 입력 및 출력 비디오 길이를 합산해 산정하며, 최소 토큰 기준이 적용될 수 있습니다. 토큰 100만 개당 $4.30이라는 요금이 비디오 참조 작업이 같은 조건의 텍스트 전용 작업보다 저렴하다는 보장은 아닙니다. 계산식에만 의존하지 말고 실제 사용량과 계정 청구 내역을 확인하세요.
  • 일부 설명은 여전히 모호합니다. Flash의 게이트웨이 스키마에는 extra.priority, extra.safety_identifier, extra.tools가 노출되어 있지만, 설명에는 여전히 “2.0 시리즈 전용”이라고 적혀 있습니다. Ark의 작업 생성 참조 문서에는 2.5 제품군에도 priority와 tools가 나열되어 있습니다. 스키마에 노출되어 있다는 사실만으로 AIHubMix에서의 효과가 확인되는 것은 아니므로, 프로덕션에서 사용하기 전에 해당 기능을 검증하세요.

사전 점검 목록

  • 비동기 작업을 활성화하고 계정 잔액을 확인하세요.
  • 짧은 Flash ID와 /ai/v1/videos를 사용하고 최신 스키마를 가져오세요.
  • 해상도는 480p 또는 720p로 선택하고, 길이는 4~30초 범위에서 명시적으로 지정하세요.
  • 참조 자료는 이미지 10개, 동영상 5개, 오디오 클립 5개 이내로 제한하세요.
  • 프레임 참조는 별도로 지정하고 해당 참조에는 적응형 비율을 사용하세요.
  • 실제 인물의 외모를 참조하는 자료는 검증을 거쳐 활성화된 에셋을 사용하세요.
  • 작업 ID를 저장하고, 작업의 최종 상태를 확인한 다음 결과물을 신속하게 다운로드하세요.
  • 생성 상태가 확실하지 않으면 기존 작업을 대상으로 상태 조회나 다운로드를 재시도하세요.

자주 묻는 질문

Flash에서 OpenAI 호환 경로인 /v1/videos를 사용할 수 있나요?
현재 Flash 스키마에는 /ai/v1/videos만 나와 있습니다. 이 가이드의 예시에는 해당 비동기 네이티브 경로를 사용하세요.

프레임 이미지 요청에서 aspect_ratio: "16:9"를 사용하면 왜 실패하나요?
비어 있지 않은 frame_images를 제공하는 경우 Flash 스키마는 aspect_ratio: "adaptive"를 요구합니다. 마지막 프레임을 지정하려면 첫 프레임도 지정해야 하며, 프레임 참조와 비어 있지 않은 input_references를 함께 사용할 수 없습니다.

doubao_real_person_required 오류는 어떻게 해결하나요?
개인 인증 및 에셋 등록 절차를 따르고, 에셋이 활성화될 때까지 기다린 뒤 에셋 URI로 참조하세요. 이 코드는 Doubao의 특정 개인정보 보호 거부를 나타내며, 이번 점검에서는 재현되지 않았습니다.

짧은 참조 동영상의 비용이 계산식으로 예상한 것보다 더 많이 나올 수 있는 이유는 무엇인가요?
입력에 동영상이 포함되면 공급업체의 요금 규칙에 따라 최소 토큰 기준이 적용될 수 있습니다. 계산식은 추정치이므로 실제 사용량과 청구 금액은 계정의 청구 내역에서 확인하세요.

실패한 생성이나 모더레이션 거부에도 요금이 부과되나요?
BytePlus와 Volcengine의 공식 요금 규칙에 따르면 성공한 생성에 요금이 부과되며, 생성 실패와 콘텐츠 모더레이션 거부에는 요금이 부과되지 않습니다. AIHubMix의 오류 문서에서는 과거 청구 내역을 확인하도록 안내합니다. 이번 점검에서는 성공 또는 실패한 생성에 대한 청구가 확인되지 않았습니다.

Flash 결과물을 다운로드할 수 있는 시간은 얼마나 되나요?
생성이 완료되면 즉시 다운로드하세요. 기존 Seedance 2.5 가이드에는 URL이 약 30분 동안 유효하다고 나와 있지만, Flash의 정확한 보관 기간은 확인되지 않았습니다. 만료 필드가 null이라고 해서 결과물이 영구 보관되는 것은 아닙니다.

AIHubMix에서 MOV 출력과 편집/연장 기능을 지원하나요?
현재 Flash 스키마에는 extra 아래에 해당 필드가 노출되어 있고, 공급업체도 이러한 기능을 문서화하고 있습니다. 하지만 생성 테스트가 할당량 부족 응답에서 중단되어 AIHubMix를 통한 전체 동작은 검증하지 못했습니다.

계속 읽기: Seedance 2.5 Flash 시리즈

출처

문서와 스키마는 2026년 11월 16일에 확인했으며, 검증 응답은 08:26 UTC에 기록했습니다. 가격은 공식 BytePlus 추정치이며, 게이트웨이에서 실제로 측정한 청구 금액이 아닙니다.

여러 AI 제공업체를 하나의 게이트웨이로. 프로덕션 환경을 위해 설계했습니다.

AIHubMix 웹사이트 방문