seedance-mcp

Сервер MCP, который позволяет Claude Code генерировать видео с помощью BytePlus ModelArk Dreamina Seedance 2.5.

Попросите Claude Code создать видео на простом языке; он отправляет задачу в BytePlus, опрашивает до завершения рендеринга и возвращает URL видео с метаданными, которые сообщает BytePlus.

1. Что он делает

Шесть инструментов через MCP stdio:

Он обрабатывает то, что легко сделать неправильно: кодирование локальных изображений и аудио в форму data-URI в Base64, которую ожидает API, проверка ограничений параметров для каждой модели до отправки запроса, повторные попытки при временных сбоях с задержкой, а также исключение ключа API из всех строк журнала и сообщений об ошибках.

2. Предварительные требования

• Python 3.11+

• uv — brew install uv или curl -LsSf https://astral.sh/uv/install.sh | sh

• Claude Code 2.x

• Учётная запись BytePlus ModelArk с ключом API и активированной моделью Seedance.

3. Настройка BytePlus

1. Создайте ключ API: Консоль ModelArk → Ключи API.

2. Активируйте модель. Seedance 2.5 не включена по умолчанию. BytePlus требует одно из:

   • баланс счёта выше 30 USD, или

   • план AI Savings Plan на уровне 30 USD или выше, или

   • пакет ресурсов Seedance с оставшейся квотой.

   Активируйте в разделе ModelArk → Активация модели → Computer Vision. Без этого создание задачи завершается ошибкой авторизации, даже если сам ключ действителен.

3. Запомните ваш регион. Базовый 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. Ключ считывается только из окружения — он никогда не записывается на диск этим сервером, не логируется и удаляется из сообщений об ошибках API перед тем, как попасть к Claude.

6. Выбор ID модели Seedance 2.5

Seedance 2.5 — это общий, общедоступный ID модели — вам не нужно создавать выделенную конечную точку. Значение по умолчанию:

dreamina-seedance-2-5-260628

Обратите внимание на префикс dreamina-. Это реальное несоответствие в именовании BytePlus: модели Dreamina 2.x имеют этот префикс, а ID версии 1.x — нет (seedance-1-5-pro-251215). Копирование ID в стиле 1.x для 2.5 — самая частая причина ошибки «модель не найдена».

Подтвердите текущий ID для вашей учётной записи в списке моделей ModelArk.

Если вы предпочитаете выделенную конечную точку (для ограничений скорости на точку, предоплаченного биллинга или мониторинга), создайте её в консоли и укажите её ID в SEEDANCE_MODEL_ID:

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

SEEDANCE_MODEL_PROFILE требуется только в этом случае: ID вида ep-... ничего не говорит о том, какая модель за ним стоит, поэтому без него сервер не может локально проверять параметры и будет передавать всё на проверку 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 покажет сервер и его шесть инструментов. Попросите:

Покажи мои последние задачи 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 — самая недорогая модель в учётной записи; во время акции, действующей до 7 сентября 2026 года, её вывод в 720p начинается примерно с 0,03 USD/сек, а 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.

Измеренный базовый уровень

По результатам одного реального запуска Seedance 2.5 text-to-video от 18.08.2026:

Это минимум: самая короткая длительность при самом низком разрешении без референсных материалов. Это также задаёт ожидания для seedance_wait_for_video, чей тайм-аут по умолчанию в 900 секунд рассчитан на задачи на порядок тяжелее этой.

Масштабирование от этого базового уровня — экстраполяция, а не измерение: использование зависит от секунд вывода и количества пикселей, поэтому 10-секундный клип в 1080p — это примерно в 2,5 раза больше секунд и ~5 раз больше пикселей, т.е. примерно в 10 раз больше этого запуска. Воспринимайте это как плановую оценку и сверяйтесь со своим биллингом.

Ловушка стоимости duration

Seedance 2.5 по умолчанию устанавливает duration равным -1, что позволяет модели выбрать любую длину до 30 секунд. Поскольку оплата идёт за секунду вывода, запрос без указания длительности может стоить примерно в 7 раз больше предполагаемого 4-секундного теста. Указывайте количество секунд явно в любом чувствительном к стоимости запуске — инструмент передаёт его напрямую, а 4 — это минимум.

Два небольших замечания: 480p и 720p исключены из текущей акционной скидки на 2.5 (скидка действует только на 1080p), поэтому 480p остаётся самым дешёвым в абсолютном выражении — скидка просто на него не распространяется. И no audio в основном сокращает время генерации; в документации нет указаний, что это снижает цену.

11. Устранение неполадок

12. Поддерживаемые функции Seedance 2.5

Типы задач (взаимоисключающие — BytePlus отклоняет смеси):

• Текст в видео — только промпт.

• Изображение в видео — first_frame, опционально плюс last_frame. Вывод начинается и заканчивается именно на этих изображениях.

• Omni reference в видео — до 30 референсных изображений, 10 референсных видео и 10 аудиоклипов, допускается ввод только аудио. Ссылайтесь на ресурсы в промпте как @Image 1, @Video 2. Охватывает три подзадачи: reference-to-video, редактирование видео и расширение видео — управляйте ими с помощью omni_reference_task_type.

Управление выводом

Медиа-входы

Подсказки работают на английском, испанском, индонезийском, португальском, японском, малайском, тайском, арабском, вьетнамском и корейском языках. Ограничьте их примерно ~1000 английских слов.

Сохранение вывода. seedance_download_video принимает ID задачи, сам находит текущий URL и потоково записывает файл на диск. По умолчанию сохраняет в ./<task_id>.mp4; передайте путь к файлу или существующую директорию как output_path. Он никогда не перезаписывает без overwrite: true, удаляет частичные файлы, если загрузка прерывается, а также может получить последний PNG с помощью include_last_frame, если задача была создана с return_last_frame. Два намеренных ограничения: загрузка идёт через собственный неаутентифицированный 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.

• Нет настраиваемых seed или camera_fixed на Seedance 2.5. Текущая документация 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), потому что модель выбирает его внутренне. Так что вы можете увидеть, какой seed создал клип, но не можете запросить его повторно — генерации 2.5 невоспроизводимы.

• Нет frames на Seedance 2.5. Длительность менее секунды через количество кадров — это функция 1.0 pro.

• Локальное видео нельзя загрузить. Изображения и аудио имеют форму Base64; видео — нет.

• Потолок тела запроса 64 MB. Встраивание нескольких больших изображений достигнет его; сервер проверяет перед отправкой и предлагает переключиться на URL.

• Настоящие человеческие лица ограничены. Seedance 2.x отклоняет референсные изображения и видео, содержащие настоящие человеческие лица, если только это не предыдущий вывод Seedance из вашей учётной записи (в течение 30 дней), предустановленный цифровой персонаж или авторизованный актив реального человека.

• Можно отменить только задачи в очереди. Как только задача запущена, она выполняется до конца.

• URL вывода живут 24 часа, с лимитом в 100 загрузок на Seedance 2.5. Оба ограничения встроены в сам подписанный 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 была перенесена из документации BytePlus 2026-08-17; перепроверьте её, если 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 генерации видео