seedance-mcp

Claude Code가 BytePlus ModelArk Dreamina Seedance 2.5로 비디오를 생성할 수 있게 해주는 MCP 서버입니다.

Claude Code에게 자연어로 비디오를 요청하면, BytePlus에 작업을 제출하고 렌더링이 완료될 때까지 폴링한 후, BytePlus가 보고하는 메타데이터와 함께 비디오 URL을 반환합니다.

1. 기능

MCP stdio를 통한 6가지 도구:

쉽게 틀릴 수 있는 부분을 처리합니다: 로컬 이미지와 오디오를 API가 기대하는 Base64 data-URI 형식으로 인코딩하고, 요청을 보내기 전에 모델별 매개변수 제한을 적용하며, 일시적인 실패를 백오프로 재시도하고, 모든 로그 줄과 오류 메시지에서 API 키를 제외합니다.

2. 사전 요구 사항

• Python 3.11+

• uv — brew install uv 또는 curl -LsSf https://astral.sh/uv/install.sh | sh

• Claude Code 2.x

• API 키와 Seedance 모델이 활성화된 BytePlus ModelArk 계정.

3. BytePlus 구성

1. API 키 생성: ModelArk 콘솔 → API 키.

2. 모델 활성화. Seedance 2.5는 기본적으로 활성화되어 있지 않습니다. BytePlus는 다음 중 하나를 요구합니다:

   • 계정 잔액이 USD 30 이상, 또는

   • USD 30 이상 등급의 AI Savings Plan, 또는

   • 할당량이 남은 Seedance 리소스 팩.

   ModelArk → 모델 활성화 → Computer Vision에서 활성화하세요. 이 작업 없이는 키 자체는 유효하더라도 작업 생성이 인증 오류로 실패합니다.

3. 지역(region) 을 확인하세요. 아래 기본 base URL은 ap-southeast(싱가포르)입니다. 계정이 다른 곳에 프로비저닝된 경우 BYTEPLUS_BASE_URL을 그에 맞게 설정하세요 — 한 지역에서 생성된 작업은 다른 지역에서 볼 수 없습니다.

4. 설치

git clone <this repo> ~/code/seedance-mcp   # or just use the directory you already have
cd ~/code/seedance-mcp
uv sync

확인:

uv run pytest -q          # 93 tests, all offline against mocked HTTP
uv run ruff check .

5. .env 설정

cp .env.example .env

그런 다음 필수 변수 하나를 입력하세요:

BYTEPLUS_API_KEY=your-modelark-api-key

나머지는 모두 선택 사항이며 이미 기본값이 설정되어 있습니다:

BYTEPLUS_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
SEEDANCE_MODEL_ID=dreamina-seedance-2-5-260628

.env는 gitignore에 포함됩니다. 키는 환경에서만 읽힙니다 — 이 서버에 의해 디스크에 기록되지 않으며, 로그에도 기록되지 않고, Claude에게 도달하기 전에 API 오류 메시지에서 제거됩니다.

6. Seedance 2.5 모델 ID 선택

Seedance 2.5는 공유되고 보편적으로 사용 가능한 모델 ID입니다 — 전용 엔드포인트를 만들 필요가 없습니다. 기본값은 다음과 같습니다:

dreamina-seedance-2-5-260628

dreamina- 접두사를 주목하세요. 이는 BytePlus 명명 규칙의 실제 불일치입니다: 2.x Dreamina 모델에는 이 접두사가 있지만, 1.x ID에는 없습니다 (seedance-1-5-pro-251215). 2.5에 1.x 형태의 ID를 복사하는 것이 "모델을 찾을 수 없음" 오류의 가장 흔한 원인입니다.

계정의 현재 ID는 ModelArk 모델 목록에서 확인하세요.

전용 엔드포인트를 선호하는 경우 (엔드포인트별 속도 제한, 선불 결제 또는 모니터링을 위해), 콘솔에서 엔드포인트를 만들고 해당 엔드포인트 ID를 SEEDANCE_MODEL_ID에 대신 넣으세요:

SEEDANCE_MODEL_ID=ep-20260817120000-abcde
SEEDANCE_MODEL_PROFILE=seedance-2.5

SEEDANCE_MODEL_PROFILE은 그 경우에만 필요합니다: ep-... ID는 그 뒤에 어떤 모델이 있는지 알려주지 않으므로, 이 프로필 없이는 서버가 매개변수를 로컬에서 검증할 수 없고 모든 것을 API에 전달하여 검증하도록 합니다.

7. Claude Code에 등록

이 디렉토리에서 (절대 경로를 사용하세요 — Claude Code는 임의의 작업 디렉토리에서 서버를 시작합니다):

claude mcp add \
  --transport stdio \
  --scope user \
  byteplus-seedance \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

--scope user는 모든 프로젝트에서 사용할 수 있게 합니다. --scope project를 사용하여 .mcp.json을 통해 저장소 협업자와 공유하거나, --scope를 생략하여 현재 프로젝트에만 사용할 수 있습니다.

서버는 자체 디렉토리에서 .env를 읽으므로 -e 플래그가 필요 없습니다. 키를 명시적으로 전달하려면:

claude mcp add --scope user byteplus-seedance \
  -e BYTEPLUS_API_KEY=your-key \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

8. 검증

claude mcp list

다음과 같은 줄이 표시될 것으로 예상합니다:

byteplus-seedance: uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp - ✓ Connected

그런 다음 Claude Code 내에서 /mcp는 서버와 그 6가지 도구를 나열합니다. 다음과 같이 요청하세요:

최근 Seedance 작업을 나열해 줘.

이것은 생성 크레딧을 소모하지 않고 인증과 연결을 테스트합니다 — 빈 목록은 성공입니다. 키가 잘못된 경우 명시적인 HTTP 401 메시지가 대신 표시됩니다.

실제로 파일을 렌더링하는 종단 간 확인을 위해서는 §10의 최소 비용 레시피를 사용하세요.

9. Claude Code 프롬프트 예시

Generate a 10-second 1080p cinematic video of Tokyo at night using Seedance 2.5.

Use ./assets/reference.png as the visual reference and generate a slow cinematic push-in shot.

Create the video and wait until generation finishes.

Generate a 15-second 9:16 vertical clip of a surfer at sunrise, no audio, and give me the URL.

Use ./assets/first.png as the first frame and ./assets/last.png as the last frame,
6 seconds, and wait for it.

Check the status of task cgt-20260817... and download the video if it's ready.

Download task cgt-20260818061514-8t2lv into ./renders/ and keep the last frame too.

Cancel task cgt-20260817... — I queued the wrong prompt.

10. 비용 및 시간

생성은 출력 초당 비용이 청구되며, 해상도와 모델에 따라 조정됩니다. 파이프라인이 작동한다는 것을 증명하는 가장 저렴한 방법은 4초 480p 클립입니다 — 4초는 모든 Seedance 2.x 모델이 허용하는 최단 길이입니다.

무료 확인, 생성 크레딧 소모 없음:

List my recent Seedance tasks.

가장 저렴한 실제 생성. Seedance 2.0 mini는 계정에서 가장 저렴한 모델입니다. 2026년 9월 7일까지 진행되는 프로모션 기간 동안 720p 출력은 약 USD 0.03/초부터 시작하며, 480p는 그보다 낮습니다:

Using Seedance model seedance-2-0-mini-260615, generate a 4-second 480p video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Then wait for it and give me the URL.

Seedance 2.5 기본 경로의 가장 저렴한 테스트 — 2.5는 다른 모델 활성화 및 다른 가격 등급이므로 별도로 실행할 가치가 있습니다:

Generate a 4-second 480p Seedance 2.5 video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Wait for it and give me the URL.

측정된 기준

2026-08-18의 실제 Seedance 2.5 텍스트-비디오 실행 기준:

이것이 최소치입니다: 참조 미디어 없이 가장 낮은 해상도에서 가장 짧은 지속 시간입니다. 또한 seedance_wait_for_video의 기대치를 설정합니다. 기본 900초 시간 제한은 이보다 한 자릿수 더 무거운 작업에 맞게 조정되었습니다.

그 기준에서 확장하는 것은 측정이 아니라 추정입니다 — 사용량은 출력 초와 픽셀 수를 따르므로, 10초 1080p 클립은 대략 2.5배의 초와 ~5배의 픽셀, 즉 이 실행의 약 10배입니다. 계획 추정치로 취급하고 자체 청구서와 대조하여 확인하세요.

duration 비용 함정

Seedance 2.5는 duration을 기본적으로 -1로 설정하며, 이는 모델이 최대 30초까지 어떤 길이든 선택할 수 있게 합니다. 출력 초당 비용이 청구되므로, 지속 시간을 명시하지 않은 요청은 의도한 4초 테스트보다 약 7배의 비용이 들 수 있습니다. 비용에 민감한 실행에서는 초 수를 명시적으로 명시하세요 — 도구는 이를 그대로 전달하며, 4가 최소값입니다.

두 가지 작은 참고 사항: 480p와 720p는 현재 2.5 프로모션 할인에서 제외되므로 (1080p만 할인됨), 480p는 절대적인 측면에서 여전히 가장 저렴합니다 — 할인이 적용되지 않을 뿐입니다. 그리고 오디오 없음은 주로 생성 시간을 단축합니다. 문서 어디에도 가격을 낮춘다고 표시되지는 않습니다.

11. 문제 해결

12. 지원되는 Seedance 2.5 기능

작업 유형 (상호 배타적 — BytePlus는 혼합을 거부합니다):

• 텍스트-비디오 — 프롬프트만.

• 이미지-비디오 — first_frame, 선택적으로 last_frame 추가. 출력은 정확히 해당 이미지에서 시작하고 끝납니다.

• 옴니 레퍼런스-비디오 — 최대 30개의 참조 이미지, 10개의 참조 비디오 및 10개의 오디오 클립을 지원하며, 오디오 전용 입력도 허용됩니다. 프롬프트에서 자산을 @Image 1, @Video 2로 인용하세요. 세 가지 하위 작업을 포함합니다: 참조-비디오, 비디오 편집, 및 비디오 확장 — omni_reference_task_type으로 제어하세요.

출력 제어

미디어 입력

프롬프트는 영어, 스페인어, 인도네시아어, 포르투갈어, 일본어, 말레이어, 태국어, 아랍어, 베트남어 및 한국어로 작동합니다. 프롬프트를 ~1000 영어 단어 미만으로 유지하세요.

출력 저장. seedance_download_video는 작업 ID를 받아 현재 URL을 직접 조회한 후 파일을 디스크로 스트리밍합니다. 기본값은 ./<task_id>.mp4이며, output_path에 파일 경로나 기존 디렉터리를 전달할 수 있습니다. overwrite: true 없이는 덮어쓰지 않으며, 다운로드가 중단되면 부분 파일을 정리하고, 작업이 return_last_frame으로 생성된 경우 include_last_frame으로 마지막 PNG도 가져올 수 있습니다. 의도된 두 가지 제한: 다운로드는 자체 인증되지 않은 HTTP 클라이언트를 통해 이루어지므로 ModelArk 키가 저장 호스트로 전송되지 않으며, URL 호스트는 .volces.com, .bytepluses.com 또는 .byteplus.com로 끝나야 합니다. 이는 범용 다운로더가 아닌 Seedance 출력 페처입니다.

서버는 또한 model 도구 인자 또는 SEEDANCE_MODEL_ID를 통해 이전 모델도 대상으로 합니다 — Seedance 2.0 / 2.0 fast / 2.0 mini, 1.5 pro, 1.0 pro 및 1.0 pro fast — 각 모델을 자체 한도에 대해 검증합니다 (예: 4K는 2.0에서는 유효하지만 2.5에서는 유효하지 않습니다).

13. 알려진 API 제한 사항

• 생성은 비동기적입니다. 어떤 것도 동기적으로 비디오를 반환하지 않습니다. 5–10초 클립은 일반적으로 몇 분이 걸리며, 1080p에서는 더 오래 걸립니다.

• Seedance 2.5에서는 설정 가능한 seed 또는 camera_fixed가 없습니다. 현재 API 참조에는 둘 다 Seedance 1.5 pro, 1.0 pro 및 1.0 pro fast 전용 입력 매개변수로 나열되어 있습니다. 이 서버는 2.5에 대해 이를 자동으로 무시하지 않고 명시적 메시지와 함께 거부합니다. 카메라 동작은 프롬프트로 표현하세요. (이전 Seedance 1.x 튜토리얼과 타사 예제에는 여전히 이러한 매개변수가 나와 있지만, 2.5에는 더 이상 적용되지 않습니다.) 실제 2.5 실행에서 관찰된 바: 작업 응답은 여전히 seed를 보고합니다 (VideoResult.seed로 표시됨, 예: 80969). 모델이 내부적으로 하나를 선택하기 때문입니다. 따라서 어떤 시드가 클립을 생성했는지 볼 수는 있지만 다시 요구할 수는 없습니다. 2.5 생성은 재현할 수 없습니다.

• Seedance 2.5에는 frames가 없습니다. 프레임 수를 통한 1초 미만 길이는 1.0 pro 기능입니다.

• 로컬 비디오는 업로드할 수 없습니다. 이미지와 오디오는 Base64 형식이 있지만 비디오는 그렇지 않습니다.

• 64 MB 요청 본문 상한. 여러 개의 큰 이미지를 인라인하면 이 한도에 도달합니다. 서버는 전송 전에 확인하고 URL로 전환하라고 안내합니다.

• 실제 사람 얼굴은 제한됩니다. Seedance 2.x는 참조 이미지와 비디오에 실제 사람 얼굴이 포함된 경우 거부합니다. 단, 자신의 계정에서 이전에 생성한 Seedance 출력(30일 이내), 사전 설정된 디지털 캐릭터, 또는 승인된 실제 인물 자산인 경우는 예외입니다.

• 대기 중인 작업만 취소할 수 있습니다. 작업이 실행되면 완료될 때까지 실행됩니다.

• 출력 URL은 24시간 동안 유효하며, Seedance 2.5에서는 100회 다운로드 상한이 있습니다. 두 제한 모두 서명된 URL 자체에 포함됩니다. 반환된 링크에는 X-Tos-Expires=86400 및 X-Tos-Max-Requests=100이 포함됩니다. 재발급 엔드포인트는 없으며, seedance_list_tasks는 해당 기간 내에 있는 URL만 반환할 수 있습니다. 보관할 가치가 있는 것은 seedance_download_video로 저장하세요. 기간이 지나면 다시 생성하는 것 외에는 방법이 없습니다.

• 작업 레코드는 7일 동안 유지됩니다.

• 참조 미디어 길이 제한은 로컬에서 확인되지 않습니다. 참조 비디오 및 오디오의 클립당(2–30초) 및 전체(30초) 제한은 미디어 프로빙이 필요합니다. 서버는 이를 위해 디코더 의존성을 추가하지 않으므로 BytePlus가 해당 제한을 적용하고 작업 오류로 보고합니다.

• 가격과 제약 조건은 변경될 수 있습니다. src/seedance_mcp/capabilities.py의 기능 표는 2026-08-17에 BytePlus 문서에서 기록한 것입니다. BytePlus가 새 모델 개정판을 출시하면 다시 확인하세요.

14. 프로젝트 레이아웃

seedance-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/seedance_mcp/
│   ├── __init__.py
│   ├── __main__.py        # stdio entry point
│   ├── server.py          # the six MCP tools
│   ├── client.py          # BytePlus HTTP client: retries, error parsing
│   ├── payload.py         # request building + validation
│   ├── capabilities.py    # per-model limits from the official docs
│   ├── media.py           # local file -> data URI, with validation
│   ├── models.py          # typed request/response models
│   ├── config.py          # environment configuration
│   └── errors.py          # error types + secret redaction
└── tests/

capabilities.py, payload.py 및 media.py는 브리프에 요약된 레이아웃에 추가된 것입니다. 문서화된 모델별 제약 표, 요청 빌더, 미디어 처리는 각각 실제 로직과 자체 테스트를 포함하며, 이를 server.py나 models.py에 통합했다면 두 파일 모두 읽기 어려웠을 것입니다.

15. 출처

위의 모든 API 세부 정보는 현재 공식 BytePlus 문서를 기준으로 검증되었습니다.

• 비디오 생성 작업 만들기

• 비디오 생성 작업 검색

• 비디오 생성 작업 목록 조회

• 비디오 생성 작업 취소 또는 삭제

• Dreamina Seedance 2.5 튜토리얼

• 모델 목록

• 비디오 생성 API 튜토리얼