seedance-mcp

An MCP server that lets Claude Code generate video with BytePlus ModelArk Dreamina Seedance 2.5.

Ask Claude Code for a video in plain language; it submits the task to BytePlus, polls until the render finishes, and hands back the video URL with the metadata BytePlus reports.

---

1. What it does

Six tools over MCP stdio:

Tool	Purpose
seedance_create_video	Submit a generation task. Returns a task ID immediately — generation is asynchronous.
seedance_get_video	One status check for a task; returns the video URL once it succeeds.
seedance_wait_for_video	Poll with backoff until the task succeeds, fails, or times out.
seedance_download_video	Save a finished video to a local file before its 24-hour URL expires.
seedance_cancel_video	Cancel a queued task, or delete a finished task's record.
seedance_list_tasks	List recent tasks, filterable by status and model.

It handles the parts that are easy to get wrong: encoding local images and audio into the Base64 data-URI form the API expects, enforcing the per-model parameter limits before a request is sent, retrying transient failures with backoff, and keeping the API key out of every log line and error message.

2. Prerequisites

• Python 3.11+
• uv — brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
• Claude Code 2.x
• A BytePlus ModelArk account with an API key and the Seedance model activated.

3. BytePlus configuration

1. Create an API key: ModelArk console → API keys.

2. Activate the model. Seedance 2.5 is not enabled by default. BytePlus requires one of:

   • account balance above USD 30, or
   • an AI Savings Plan at the USD 30 tier or above, or
   • a Seedance resource pack with quota remaining.

   Activate under ModelArk → Model activation → Computer Vision. Without this, task creation fails with an authorization error even though the key itself is valid.

3. Note your region. The default base URL below is ap-southeast (Singapore). If your account is provisioned elsewhere, set BYTEPLUS_BASE_URL accordingly — a task created in one region is not visible from another.

4. Installation

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

Verify:

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

5. .env setup

cp .env.example .env

Then fill in one required variable:

BYTEPLUS_API_KEY=your-modelark-api-key

Everything else is optional and already defaulted:

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

.env is gitignored. The key is read from the environment only — it is never written to disk by this server, never logged, and is scrubbed from API error messages before they reach Claude.

6. Choosing the Seedance 2.5 model ID

Seedance 2.5 is a shared, universally available model ID — you do not need to create a dedicated endpoint. The default is:

dreamina-seedance-2-5-260628

Note the dreamina- prefix. This is a real inconsistency in BytePlus's naming: the 2.x Dreamina models carry it, while the 1.x IDs do not (seedance-1-5-pro-251215). Copying a 1.x-shaped ID for 2.5 is the most common cause of a "model not found" error.

Confirm the current ID for your account in the ModelArk model list.

If you prefer a dedicated endpoint (for per-endpoint rate limits, prepaid billing, or monitoring), create one in the console and put its endpoint ID in SEEDANCE_MODEL_ID instead:

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

SEEDANCE_MODEL_PROFILE is needed only in that case: an ep-... ID says nothing about which model sits behind it, so without it the server cannot validate parameters locally and will pass everything through to the API for validation instead.

7. Register with Claude Code

From this directory (use the absolute path — Claude Code launches the server from arbitrary working directories):

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

--scope user makes it available in every project. Use --scope project to share it with a repo's collaborators via .mcp.json, or omit --scope for the current project only.

The server reads .env from its own directory, so no -e flags are needed. If you would rather pass the key explicitly:

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. Verification

claude mcp list

Expect a line like:

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

Then inside Claude Code, /mcp lists the server and its six tools. Ask it:

List my recent Seedance tasks.

That exercises authentication and connectivity without spending generation credits — an empty list is a success. If the key is wrong you get an explicit HTTP 401 message instead.

For an end-to-end check that actually renders a file, use the minimum-cost recipe in §10.

9. Example Claude Code prompts

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. Cost and timing

Generation is billed per second of output, scaled by resolution and model. The cheapest way to prove the pipeline works is a 4-second 480p clip — 4s is the shortest length any Seedance 2.x model accepts.

Free check, no generation credits spent:

List my recent Seedance tasks.

Cheapest real generation. Seedance 2.0 mini is the least expensive model on the account; during the promotion running to 7 Sep 2026 its 720p output starts around USD 0.03/second, and 480p sits below that:

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.

Cheapest test of the Seedance 2.5 default path — worth running separately, since 2.5 is a different model activation and a different price tier:

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.

Measured baseline

From one real Seedance 2.5 text-to-video run on 2026-08-18:

Output	Wall-clock	Reported usage
4s · 480p · 16:9 · 24 fps · silent	~105 s	38,830 tokens

That is the floor: the shortest duration at the lowest resolution with no reference media. It also sets expectations for seedance_wait_for_video, whose 900-second default timeout is sized for jobs an order of magnitude heavier than this one.

Scaling from that baseline is extrapolation, not measurement — usage tracks output seconds and pixel count, so a 10-second 1080p clip is roughly 2.5× the seconds and ~5× the pixels, i.e. of order 10× this run. Treat it as a planning estimate and confirm against your own billing.

The duration cost trap

Seedance 2.5 defaults duration to -1, which lets the model pick any length up to 30 seconds. Since billing is per second of output, a request that doesn't state a duration can cost around 7× an intended 4-second test. State the number of seconds explicitly in any cost-sensitive run — the tool passes it straight through, and 4 is the floor.

Two smaller notes: 480p and 720p are excluded from the current 2.5 promotional discount (only 1080p is discounted), so 480p remains cheapest in absolute terms — the discount simply doesn't apply to it. And no audio mainly shortens generation time; nothing in the documentation shows it reduces the price.

11. Troubleshooting

Symptom	Cause and fix
BYTEPLUS_API_KEY is not set	No .env next to the project, or an empty value. The server resolves config on the first tool call, so this appears as a tool error rather than a startup failure.
HTTP 401	Wrong or revoked key, or a key from a different BytePlus account than the one holding the model activation.
HTTP 404 on a task ID	The task was created in a different region, or it is older than 7 days (BytePlus purges task records after 7 days).
Model-not-found on create	SEEDANCE_MODEL_ID is wrong — check the dreamina- prefix — or Seedance 2.5 is not activated on the account (see §3).
HTTP 429	Rate limited. The client already retries with backoff and honours Retry-After; persistent 429s mean your account RPM is exhausted.
Local video files cannot be uploaded	Expected. BytePlus accepts reference video only as a public URL or asset:// ID. Host the file first.
Task fails with InvalidParameter.TaskTypeConstraint	Seedance 2.5 inferred a different task type than your parameters allow. Set omni_reference_task_type explicitly to edit or extend so validation happens at submit time.
video_url returns 403	Output URLs expire 24 hours after completion, and Seedance 2.5 URLs allow at most 100 downloads. Re-generate, or configure BytePlus TOS data subscription for durable storage. Use seedance_download_video to save files inside the window.
File already exists on download	Guard against clobbering a previous render. Pass overwrite: true, or give a different output_path.
Refusing to download from <host>	seedance_download_video only fetches BytePlus-hosted output. Fetch other URLs outside this server.
Server shows as failed in claude mcp list	Run the command by hand — uv --directory /path run python -m seedance_mcp — and read stderr. Usually a stale venv; uv sync fixes it.

12. Supported Seedance 2.5 features

Task types (mutually exclusive — BytePlus rejects mixtures):

• Text-to-video — prompt only.
• Image-to-video — first_frame, optionally plus last_frame. The output starts and ends on exactly those images.
• Omni reference-to-video — up to 30 reference images, 10 reference videos and 10 audio clips, with audio-only input allowed. Cite assets in the prompt as @Image 1, @Video 2. Covers three sub-tasks: reference-to-video, video editing, and video extension — steer them with omni_reference_task_type.

Output controls

Parameter	Seedance 2.5 values
resolution	480p, 720p (default), 1080p
ratio	16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (default)
duration	4–30 seconds, or -1 to let the model choose (default)
generate_audio	true (default) — synchronised speech, effects and music
watermark	false (default)
return_last_frame	false (default) — returns the closing frame as PNG to chain clips
omni_reference_task_type	auto, edit, extend
service_tier	default (online) or flex (cheaper offline inference)

Media inputs

Type	Formats	Per-file limit	Local file support
Image	jpeg, png, webp, bmp, tiff, gif, heic, heif	30 MB	✅ inlined as Base64
Audio	wav, mp3	15 MB	✅ inlined as Base64
Video	mp4, mov	200 MB	❌ public URL or asset:// only

Prompts work in English, Spanish, Indonesian, Portuguese, Japanese, Malay, Thai, Arabic, Vietnamese and Korean. Keep them under ~1000 English words.

Saving output. seedance_download_video takes a task ID, looks up the current URL itself, and streams the file to disk. Defaults to ./<task_id>.mp4; pass a file path or an existing directory as output_path. It never overwrites without overwrite: true, cleans up partial files if a download breaks, and can also fetch the closing PNG with include_last_frame when the task was created with return_last_frame. Two deliberate restrictions: downloads go over its own unauthenticated HTTP client, so the ModelArk key is never sent to the storage host, and the URL host must end in .volces.com, .bytepluses.com or .byteplus.com — this is a Seedance output fetcher, not a general-purpose downloader.

The server also targets older models via the model tool argument or SEEDANCE_MODEL_ID — Seedance 2.0 / 2.0 fast / 2.0 mini, 1.5 pro, 1.0 pro and 1.0 pro fast — validating each against its own limits (for example 4K is valid on 2.0 but not on 2.5).

13. Known API limitations

• Generation is asynchronous. Nothing returns a video synchronously; a 5–10 second clip typically takes a few minutes, longer at 1080p.

• No settable seed or camera_fixed on Seedance 2.5. The current API reference lists both as input parameters for Seedance 1.5 pro, 1.0 pro and 1.0 pro fast only. This server rejects them for 2.5 with an explicit message rather than silently dropping them. Express camera behaviour in the prompt instead. (Older Seedance 1.x tutorials and third-party examples still show these parameters — they no longer apply to 2.5.)

  Observed in a real 2.5 run: the task response still reports a seed (surfaced as VideoResult.seed, e.g. 80969), because the model picks one internally. So you can see which seed produced a clip, but you cannot ask for it back — 2.5 generations are not reproducible.

• No frames on Seedance 2.5. Sub-second durations via frame count are a 1.0 pro feature.

• Local video cannot be uploaded. Images and audio have a Base64 form; video does not.

• 64 MB request-body ceiling. Inlining several large images will hit it; the server checks before sending and tells you to switch to URLs.

• Real human faces are restricted. Seedance 2.x rejects reference images and videos containing real human faces unless they are a prior Seedance output from your own account (within 30 days), a preset digital character, or an authorised real-person asset.

• Only queued tasks can be cancelled. Once a task is running, it runs to completion.

• Output URLs live 24 hours, with a 100-download cap on Seedance 2.5. Both limits are baked into the signed URL itself — a returned link carries X-Tos-Expires=86400 and X-Tos-Max-Requests=100. There is no re-issue endpoint, and seedance_list_tasks can only hand back a URL that is still inside that window. Use seedance_download_video to save anything worth keeping; once the window closes the only remedy is to generate again.

• Task records live 7 days.

• Reference-media duration limits are not checked locally. Per-clip (2–30s) and total (30s) limits for reference video and audio need media probing; the server does not add a decoder dependency for it, so BytePlus enforces those and reports them as task errors.

• Prices and constraints change. The capability table in src/seedance_mcp/capabilities.py was transcribed from the BytePlus docs on 2026-08-17; re-check it if BytePlus ships a new model revision.

14. Project layout

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 and media.py are additions to the layout sketched in the brief: the documented per-model constraint table, the request builder and the media handling each carry real logic and their own tests, and folding them into server.py or models.py would have made both hard to read.

15. Sources

Every API detail above was verified against current official BytePlus documentation:

• Create a video generation task
• Retrieve a video generation task
• List video generation tasks
• Cancel or delete a video generation task
• Dreamina Seedance 2.5 tutorial
• Model list
• Video generation API tutorial