Seedance 2.5 API calls its 4K route an upscale, and the repository description calls it native

The higher resolution routes are upscaled from a 720p render

The repository description advertises native 4K. The readme says something different, in a note placed directly under the feature list:

The 1080p and 4K routes are upscaled from the model's 720p base render. They are separate routes and are priced above the standard 720p tier.

So the model renders at 720p and the higher tiers are computed from that output. The readme is not hiding this, which is to its credit, and it also notes that they are separate routes rather than a flag on the same call, and that they cost more. What it means for a user is that 4K here is a different computation with an upscaler in it, not more detail from the model, and that the usual question of whether an upscale holds up has to be answered by looking rather than by reading a spec.

The description and the readme disagree in a way that matters for procurement. A description is what a buyer sees in a listing, and it says native 4K, which is the phrase people use for detail captured rather than computed. The readme's note is the accurate one.

The same note explains the pricing ladder. Four tiers exist, 480p for fast drafts, 720p as the standard, and the two upscaled routes above it, so a cost model for a project that needs high resolution has to be built from the upscaled prices rather than the standard one.

Six workflows, three variants and four tiers multiply to seventy two routes

The route count is worth unpacking, because the file presents 72 as a headline number and it decomposes exactly. There are six workflow families: text to video, image to video, first and last frame, Omni Reference, video edit, and video extend. Each is available in three variants, described as standard, international, and Spicy. Each of those comes in four resolution tiers. Six times three times four is seventy two, so there is no hidden fifth dimension.

The Spicy variant is the one to look at first. The feature list describes it as selecting a route family with more permissive content safety without changing the request shape, and the same list sells reduced censorship as a feature in its own right. That is an unusual thing for a wrapper to advertise, and it means the request your code writes can be sent to a differently policed model depending on a parameter, which is a decision about content policy that belongs to whoever runs the application.

The input limits are the other numbers worth having. Clips run from 4 to 30 seconds, with the 30 second ceiling described as double the 15 second limit of the previous version. Omni Reference accepts a combination of reference media in one request, up to 30 images, 10 videos and 10 audio clips. Aspect ratios cover seven shapes including the vertical formats used by short video platforms.

So the surface is wide, but it is a regular grid, and the useful question for an integrator is how many of the 72 combinations you actually need, because each is a separate priced call.

The PyPI name and a related project share almost the same name

The package you install is not named after the repository. The manifest declares:

[project]
name = "seedance-2-api"
version = "0.3.0"

The repository is Seedance-2.5-API, so the distribution name drops both the dot and the minor version. The PyPI badge at the top of the readme points at the distribution, which is the correct link for an install command, but it means the readme's badge and its own title refer to two different names.

That collision has a consequence in the wild. The related projects list includes an entry named Seedance-2-API from a different account, described as a Python wrapper covering Seedance 2.0 and the Mini variant. Two packages that differ by a version number, an organisation and a repository, with nearly identical names and the same function, is the sort of thing that installs the wrong one.

The authorship is split the same way. The manifest lists a single author, Anil Matcha, while the repository sits under the SamurAIGPT organisation, and most of the related projects are attributed to that same individual account rather than to the organisation.

Version 0.3.0 is published, and there are no GitHub releases for the repository, so the version that exists is only visible on the package index. The last push to the branch is dated 2026-09-23.

The same metadata is declared twice, in two build files

The repository carries both a pyproject.toml and a setup.py, and they restate the same package in full. The name, the version 0.3.0, the author, the description, the module list, the three dependencies, the three classifiers and the Python floor all appear in both files.

A dual declaration is not automatically wrong, but it is a maintenance liability with a specific failure mode. A release that bumps the version in one file and not the other will publish one version number while the metadata claims another, and nothing in the build catches it because each file is internally consistent.

There are two smaller tells that the two files have drifted at the edges already. The modern file declares its modules with the tool.setuptools py-modules key while the legacy file uses the older py_modules spelling, which is fine but is the kind of difference that appears when one file is regenerated and the other is not. And setup.py reads the readme with a bare open call and no encoding, which is a portability hazard on a machine whose default encoding is not UTF-8.

The module list itself is short, and worth checking against the tree. Two modules are declared, the library and the server, while the repository also carries a third Python file used by the source install path.

The build backend is setuptools at 61 or later, and the only dependencies are requests, python-dotenv and the MCP extra.

An MCP server dependency is mandatory whether you use it or not

All three dependencies are unconditional:

requests
python-dotenv
mcp[cli]

The third one is the surprise. The MCP server is described in the readme as new, with the model context protocol letting AI models drive Seedance 2.5, and the repository ships a dedicated server module alongside the library. Nothing marks that dependency as an extra, so every install of the library pulls the protocol SDK and its command line extra whether the caller ever launches a server.

For a thin HTTP wrapper that is a heavy default. Requests and python-dotenv are what the client needs; the server is a separate surface with a separate audience.

The repository also carries a skills directory and a documentation file on character consistency, so this project is being packaged for agents on three fronts at once: as a Python library, as an MCP server, and as a set of agent skills. The related projects list pushes the same idea outward with separate MCP servers scoped to particular routes and a ComfyUI node package, which suggests the wrapper is one entry point in a wider set of integrations rather than a standalone client.

Configuration is one environment variable, a key for the aggregator gateway, read from a .env file in the project root. The example file contains that single line and nothing else.

Early access means a plan gate, not just an API key

The access note is short and it changes what the wrapper can promise you. Seedance 2.5 is described as an early access build on the aggregator, gated to Pro and Business plan accounts.

So the key in your .env file is not sufficient on its own. The account behind it has to be on one of two plan levels, which means the wrapper cannot be exercised by anyone with a free key, and a test written against it will not run for a colleague without that plan.

The commercial chain is also worth naming plainly. The wrapper is described as the most complete Python wrapper for the API, delivered via the aggregator, and every badge, playground link and call to action on the page carries the aggregator's own tracking parameters. The model belongs to ByteDance. The endpoint, the billing and the plan gate belong to the aggregator, and the wrapper is the client of that endpoint rather than of the model.

That arrangement explains most of what is otherwise odd about the readme. Seventy two routes, an international variant, a permissive variant and per-tier pricing are all features of the reseller's catalogue. They are not guarantees about the model itself, and a change to the aggregator's plan names would be visible to every user of this package at once.

What the wrapper does own is the request shape and the local ergonomics: a typed call for image to video taking an image URL, an upload helper for local files, a seed parameter, and a two step character consistency flow.

Character consistency is a two step workflow, not a parameter

Consistent identity across shots is presented as a workflow with two calls rather than a switch. The first generates a character sheet from one to three reference photos, described as a multi panel result covering front, back, side, action pose and expressions. The second anchors an Omni Reference generation onto that sheet through a dedicated helper.

So producing a character that holds still across several clips means first building a canonical depiction, then pointing every subsequent generation at it. That is a materially different design from a reference image parameter, because the sheet is derived once and reused, and it explains why the repository carries a separate document devoted to the topic.

The reproducibility feature beside it is deliberately weaker than the name suggests. Passing a seed keeps generations in the same neighbourhood across repeated calls, which is a statement about similarity rather than identity, and the distinction is the right one to hold when you are trying to reproduce a result.

Two other conveniences round out the client surface. Local images and videos can be uploaded directly with an upload method rather than being passed as a URL, and seven aspect ratios are supported, including the vertical and square shapes that short video and social formats need.

Community infrastructure is thin but present: a video walkthrough on getting a key and making a first call, a subreddit for discussion, and separate playground pages for the image to video and text to video routes.

Editorial conclusion

This wrapper is a thin client, and that is its main virtue and its main limit. It gives you a typed surface over 72 routes on someone else's gateway, so you inherit that gateway's pricing, its plan requirement and its content policy variants, none of which the wrapper controls. Two things to check before you build on it. Decide whether the resolution tiers meet your requirement, since the readme states the higher tiers are upscaled from a 720p base render and cost more, which the repository description does not mention. And decide whether you can live with a package that declares its metadata in two files and ships an MCP server dependency whether you want it or not.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. SamurAIGPT/Seedance-2.5-API on GitHub