seedance-mcp

Ein MCP-Server, der es Claude Code ermöglicht, Videos mit BytePlus ModelArk Dreamina Seedance 2.5 zu generieren.

Bitten Sie Claude Code in einfacher Sprache um ein Video; es übermittelt die Aufgabe an BytePlus, fragt nach, bis der Render-Vorgang abgeschlossen ist, und gibt die Video-URL zusammen mit den von BytePlus gemeldeten Metadaten zurück.

1. Was es tut

Sechs Tools über MCP stdio:

Es kümmert sich um die Teile, die leicht falsch gemacht werden können: Kodieren lokaler Bilder und Audiodaten in die vom API erwartete Base64-Daten-URI-Form, Durchsetzung der modellspezifischen Parameterlimits bevor eine Anfrage gesendet wird, Wiederholung vorübergehender Fehler mit Backoff und das Fernhalten des API-Schlüssels aus jeder Logzeile und Fehlermeldung.

2. Voraussetzungen

• Python 3.11+

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

• Claude Code 2.x

• Ein BytePlus ModelArk-Konto mit einem API-Schlüssel und dem aktivierten Seedance-Modell.

3. BytePlus-Konfiguration

1. Erstellen Sie einen API-Schlüssel: ModelArk-Konsole → API-Schlüssel.

2. Aktivieren Sie das Modell. Seedance 2.5 ist standardmäßig nicht aktiviert. BytePlus erfordert eine der folgenden Optionen:

   • Kontoguthaben über USD 30, oder

   • einen AI-Sparplan der Stufe USD 30 oder höher, oder

   • ein Seedance-Ressourcenpaket mit verbleibendem Kontingent.

   Aktivieren Sie es unter ModelArk → Modellaktivierung → Computer Vision. Ohne dies schlägt die Aufgabenerstellung mit einem Autorisierungsfehler fehl, obwohl der Schlüssel selbst gültig ist.

3. Notieren Sie Ihre Region. Die Standard-Basis-URL unten ist ap-southeast (Singapur). Wenn Ihr Konto woanders bereitgestellt ist, setzen Sie BYTEPLUS_BASE_URL entsprechend – eine in einer Region erstellte Aufgabe ist von einer anderen aus nicht sichtbar.

4. Installation

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

Überprüfung:

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

5. .env-Einrichtung

cp .env.example .env

Füllen Sie dann eine erforderliche Variable aus:

BYTEPLUS_API_KEY=your-modelark-api-key

Alles andere ist optional und bereits voreingestellt:

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

.env ist in der gitignore. Der Schlüssel wird nur aus der Umgebung gelesen – er wird von diesem Server nie auf die Festplatte geschrieben, nie protokolliert und aus API-Fehlermeldungen entfernt, bevor sie Claude erreichen.

6. Auswahl der Seedance 2.5-Modell-ID

Seedance 2.5 ist eine gemeinsame, universell verfügbare Modell-ID – Sie müssen keinen dedizierten Endpunkt erstellen. Der Standardwert ist:

dreamina-seedance-2-5-260628

Beachten Sie das Präfix dreamina-. Dies ist eine echte Inkonsistenz in der Namensgebung von BytePlus: Die Dreamina-Modelle der 2.x-Reihe tragen es, während die IDs der 1.x-Reihe es nicht tun (seedance-1-5-pro-251215). Das Kopieren einer 1.x-förmigen ID für 2.5 ist die häufigste Ursache für einen Fehler "Modell nicht gefunden".

Bestätigen Sie die aktuelle ID für Ihr Konto in der ModelArk-Modellliste.

Wenn Sie einen dedizierten Endpunkt bevorzugen (für Ratenbegrenzungen pro Endpunkt, Vorauszahlung oder Überwachung), erstellen Sie einen in der Konsole und setzen Sie dessen Endpunkt-ID stattdessen in SEEDANCE_MODEL_ID:

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

SEEDANCE_MODEL_PROFILE wird nur in diesem Fall benötigt: Eine ep-...-ID sagt nichts darüber aus, welches Modell dahintersteckt, sodass der Server ohne sie keine Parameter lokal validieren kann und alles zur Validierung an die API weiterleitet.

7. Bei Claude Code registrieren

Führen Sie dies von diesem Verzeichnis aus (verwenden Sie den absoluten Pfad – Claude Code startet den Server aus beliebigen Arbeitsverzeichnissen):

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

--scope user macht es in jedem Projekt verfügbar. Verwenden Sie --scope project, um es mit den Mitarbeitern eines Repositorys über .mcp.json zu teilen, oder lassen Sie --scope weg, um es nur für das aktuelle Projekt zu verwenden.

Der Server liest .env aus seinem eigenen Verzeichnis, daher sind keine -e-Flags erforderlich. Wenn Sie den Schlüssel lieber explizit übergeben möchten:

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. Überprüfung

claude mcp list

Erwarten Sie eine Zeile wie:

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

Dann listet /mcp innerhalb von Claude Code den Server und seine sechs Tools auf. Fragen Sie es:

Liste meine aktuellen Seedance-Aufgaben auf.

Das testet Authentifizierung und Konnektivität, ohne Generierungsguthaben zu verbrauchen – eine leere Liste ist ein Erfolg. Wenn der Schlüssel falsch ist, erhalten Sie stattdessen eine explizite HTTP 401-Meldung.

Für eine End-to-End-Überprüfung, die tatsächlich eine Datei rendert, verwenden Sie das Rezept mit den minimalen Kosten in §10.

9. Beispielhafte Claude Code-Eingabeaufforderungen

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. Kosten und Zeitplanung

Die Generierung wird pro Sekunde Ausgabe abgerechnet, skaliert nach Auflösung und Modell. Der günstigste Weg, um zu beweisen, dass die Pipeline funktioniert, ist ein 4-Sekunden-480p-Clip – 4s ist die kürzeste Länge, die jedes Seedance 2.x-Modell akzeptiert.

Kostenlose Überprüfung, keine Generierungsguthaben ausgegeben:

List my recent Seedance tasks.

Günstigste echte Generierung. Seedance 2.0 mini ist das günstigste Modell auf dem Konto; während der bis zum 7. September 2026 laufenden Aktion beginnen die Kosten für 720p-Ausgabe bei etwa USD 0,03/Sekunde, und 480p liegt darunter:

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.

Günstigster Test des Seedance 2.5-Standardpfads – es lohnt sich, dies separat auszuführen, da 2.5 eine andere Modellaktivierung und eine andere Preisstufe ist:

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.

Gemessene Basislinie

Von einem echten Seedance 2.5 Text-zu-Video-Durchlauf vom 18.08.2026:

Das ist das Minimum: die kürzeste Dauer bei der niedrigsten Auflösung ohne Referenzmaterial. Es setzt auch die Erwartungen für seedance_wait_for_video, dessen Standard-Timeout von 900 Sekunden für Aufgaben ausgelegt ist, die eine Größenordnung schwerer sind als diese.

Die Skalierung von dieser Basislinie ist eine Extrapolation, keine Messung – die Nutzung folgt den Ausgabesekunden und der Pixelanzahl, daher ist ein 10-Sekunden-1080p-Clip ungefähr 2,5× die Sekunden und ~5× die Pixel, d.h. in der Größenordnung von 10× diesem Durchlauf. Behandeln Sie es als Planungsschätzung und bestätigen Sie es anhand Ihrer eigenen Abrechnung.

Die Kostenfalle duration

Seedance 2.5 setzt duration standardmäßig auf -1, was dem Modell erlaubt, jede Länge bis zu 30 Sekunden zu wählen. Da die Abrechnung pro Sekunde Ausgabe erfolgt, kann eine Anfrage, die keine Dauer angibt, etwa das 7-fache eines beabsichtigten 4-Sekunden-Tests kosten. Geben Sie die Anzahl der Sekunden bei jedem kostenrelevanten Durchlauf explizit an – das Tool leitet sie direkt durch, und 4 ist das Minimum.

Zwei kleinere Anmerkungen: 480p und 720p sind vom aktuellen 2.5-Aktionsrabatt ausgeschlossen (nur 1080p wird rabattiert), daher bleibt 480p in absoluten Zahlen am günstigsten – der Rabatt gilt einfach nicht dafür. Und kein Audio verkürzt hauptsächlich die Generierungszeit; nichts in der Dokumentation zeigt, dass es den Preis senkt.

11. Fehlerbehebung

12. Unterstützte Seedance 2.5-Funktionen

Aufgabentypen (sich gegenseitig ausschließend – BytePlus lehnt Mischungen ab):

• Text-zu-Video – nur Prompt.

• Bild-zu-Video – first_frame, optional plus last_frame. Die Ausgabe beginnt und endet genau mit diesen Bildern.

• Omni-Referenz-zu-Video – bis zu 30 Referenzbilder, 10 Referenzvideos und 10 Audioclips, wobei Nur-Audio-Eingabe erlaubt ist. Zitieren Sie Assets im Prompt als @Bild 1, @Video 2. Umfasst drei Unteraufgaben: Referenz-zu-Video, Videobearbeitung und Videoerweiterung – steuern Sie sie mit omni_reference_task_type.

Ausgabesteuerungen

Medieneingaben

Prompts funktionieren auf Englisch, Spanisch, Indonesisch, Portugiesisch, Japanisch, Malaiisch, Thailändisch, Arabisch, Vietnamesisch und Koreanisch. Halten Sie sie unter ~1000 englischen Wörtern.

Ausgabe speichern. seedance_download_video nimmt eine Aufgaben-ID, sucht selbst die aktuelle URL und streamt die Datei auf die Festplatte. Standardmäßig nach ./<task_id>.mp4; übergeben Sie einen Dateipfad oder ein vorhandenes Verzeichnis als output_path. Es überschreibt nie ohne overwrite: true, bereinigt Teil-Dateien, wenn ein Download abbricht, und kann auch das Schluss-PNG mit include_last_frame abrufen, wenn die Aufgabe mit return_last_frame erstellt wurde. Zwei bewusste Einschränkungen: Downloads erfolgen über einen eigenen nicht authentifizierten HTTP-Client, sodass der ModelArk-Schlüssel niemals an den Speicherhost gesendet wird, und der URL-Host muss auf .volces.com, .bytepluses.com oder .byteplus.com enden – dies ist ein Seedance-Ausgabeabrufer, kein Allzweck-Downloader.

Der Server zielt auch auf ältere Modelle über das model-Tool-Argument oder SEEDANCE_MODEL_ID ab — Seedance 2.0 / 2.0 fast / 2.0 mini, 1.5 pro, 1.0 pro und 1.0 pro fast — und validiert jedes gegen seine eigenen Grenzen (z. B. ist 4K bei 2.0 gültig, aber nicht bei 2.5).

13. Bekannte API-Einschränkungen

• Die Generierung ist asynchron. Nichts gibt ein Video synchron zurück; ein 5–10 Sekunden langer Clip dauert in der Regel ein paar Minuten, länger bei 1080p.

• Kein einstellbarer seed oder camera_fixed bei Seedance 2.5. Die aktuelle API-Referenz listet beide nur als Eingabeparameter für Seedance 1.5 pro, 1.0 pro und 1.0 pro fast. Dieser Server lehnt sie für 2.5 mit einer expliziten Nachricht ab, anstatt sie stillschweigend zu ignorieren. Drücken Sie das Kameraverhalten stattdessen im Prompt aus. (Ältere Seedance-1.x-Tutorials und Beispiele von Drittanbietern zeigen diese Parameter noch — sie gelten nicht mehr für 2.5.)

  In einem echten 2.5-Lauf beobachtet: Die Aufgaben-Antwort meldet immer noch einen seed (angezeigt als VideoResult.seed, z. B. 80969), weil das Modell intern einen auswählt. Sie können also sehen, welcher Seed einen Clip erzeugt hat, aber Sie können ihn nicht zurückfordern — 2.5-Generierungen sind nicht reproduzierbar.

• Kein frames bei Seedance 2.5. Unter-Sekunden-Dauern über die Bildanzahl sind ein Feature von 1.0 pro.

• Lokales Video kann nicht hochgeladen werden. Bilder und Audio haben eine Base64-Form; Video nicht.

• 64-MB-Anforderungskörper-Obergrenze. Das Einbetten mehrerer großer Bilder wird sie erreichen; der Server prüft vor dem Senden und sagt Ihnen, auf URLs umzusteigen.

• Echte menschliche Gesichter sind eingeschränkt. Seedance 2.x lehnt Referenzbilder und -videos mit echten menschlichen Gesichtern ab, es sei denn, es handelt sich um eine frühere Seedance-Ausgabe Ihres eigenen Kontos (innerhalb von 30 Tagen), eine voreingestellte digitale Figur oder eine autorisierte reale Person.

• Nur eingereihte Aufgaben können abgebrochen werden. Sobald eine Aufgabe läuft, läuft sie bis zum Ende.

• Ausgabe-URLs leben 24 Stunden, mit einer Obergrenze von 100 Downloads bei Seedance 2.5. Beide Grenzen sind in die signierte URL selbst eingebaut – ein zurückgegebener Link trägt X-Tos-Expires=86400 und X-Tos-Max-Requests=100. Es gibt keinen Endpunkt zur Neuausstellung, und seedance_list_tasks kann nur eine URL zurückgeben, die sich noch in diesem Fenster befindet. Verwenden Sie seedance_download_video, um alles Erhaltenswerte zu speichern; sobald das Fenster schließt, ist die einzige Abhilfe, erneut zu generieren.

• Aufgabenaufzeichnungen leben 7 Tage.

• Referenz-Medien-Dauerbeschränkungen werden nicht lokal geprüft. Grenzen pro Clip (2–30s) und gesamt (30s) für Referenzvideo und -audio erfordern Medien-Probing; der Server fügt keine Decoder-Abhängigkeit dafür hinzu, daher erzwingt BytePlus diese und meldet sie als Aufgabenfehler.

• Preise und Einschränkungen ändern sich. Die Fähigkeitentabelle in src/seedance_mcp/capabilities.py wurde am 2026-08-17 aus den BytePlus-Dokumenten transkribiert; überprüfen Sie sie erneut, wenn BytePlus eine neue Modellrevision veröffentlicht.

14. Projektstruktur

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 und media.py sind Ergänzungen zur in der Aufgabenbeschreibung skizzierten Struktur: die dokumentierte modellspezifische Einschränkungstabelle, der Anforderungsgenerator und die Medienverarbeitung tragen jeweils echte Logik und ihre eigenen Tests, und sie in server.py oder models.py zu integrieren hätte beide schwer lesbar gemacht.

15. Quellen

Jedes API-Detail oben wurde anhand der aktuellen offiziellen BytePlus-Dokumentation verifiziert:

• Erstellen einer Video-Generierungsaufgabe

• Abrufen einer Video-Generierungsaufgabe

• Auflisten von Video-Generierungsaufgaben

• Abbrechen oder Löschen einer Video-Generierungsaufgabe

• Dreamina Seedance 2.5-Tutorial

• Modellliste

• Video-Generierungs-API-Tutorial