seedance-mcp

Un servidor MCP que permite a Claude Code generar video con BytePlus ModelArk Dreamina Seedance 2.5.

Pídele a Claude Code un video en lenguaje natural; este envía la tarea a BytePlus, consulta hasta que la renderización finaliza y devuelve la URL del video con los metadatos que BytePlus reporta.

1. Qué hace

Seis herramientas a través de MCP stdio:

Maneja las partes que son fáciles de hacer mal: codificar imágenes y audio locales en la forma de URI de datos Base64 que la API espera, aplicar los límites de parámetros por modelo antes de que se envíe una solicitud, reintentar fallos transitorios con retroceso y mantener la clave API fuera de cada línea de registro y mensaje de error.

2. Requisitos previos

• Python 3.11+

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

• Claude Code 2.x

• Una cuenta de BytePlus ModelArk con una clave API y el modelo Seedance activado.

3. Configuración de BytePlus

1. Crear una clave API: Consola de ModelArk → Claves API.

2. Activar el modelo. Seedance 2.5 no está habilitado por defecto. BytePlus requiere una de:

   • saldo de cuenta superior a 30 USD, o

   • un Plan de Ahorro de IA en el nivel de 30 USD o superior, o

   • un paquete de recursos de Seedance con cuota restante.

   Activar en ModelArk → Activación de modelos → Visión por computadora. Sin esto, la creación de tareas falla con un error de autorización aunque la clave en sí sea válida.

3. Anota tu región. La URL base predeterminada a continuación es ap-southeast (Singapur). Si tu cuenta está aprovisionada en otro lugar, configura BYTEPLUS_BASE_URL en consecuencia — una tarea creada en una región no es visible desde otra.

4. Instalación

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

Verificar:

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

5. Configuración de .env

cp .env.example .env

Luego completa una variable requerida:

BYTEPLUS_API_KEY=your-modelark-api-key

Todo lo demás es opcional y ya tiene valores predeterminados:

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

.env está en gitignore. La clave se lee solo del entorno — nunca es escrita en el disco por este servidor, nunca se registra y se elimina de los mensajes de error de la API antes de que lleguen a Claude.

6. Elegir el ID del modelo Seedance 2.5

Seedance 2.5 es un ID de modelo compartido y universalmente disponible — no necesitas crear un endpoint dedicado. El valor predeterminado es:

dreamina-seedance-2-5-260628

Nota el prefijo dreamina-. Esta es una inconsistencia real en la nomenclatura de BytePlus: los modelos 2.x Dreamina lo llevan, mientras que los IDs 1.x no (seedance-1-5-pro-251215). Copiar un ID con forma de 1.x para 2.5 es la causa más común de un error "modelo no encontrado".

Confirma el ID actual para tu cuenta en la lista de modelos de ModelArk.

Si prefieres un endpoint dedicado (para límites de tasa por endpoint, facturación prepaga o monitoreo), crea uno en la consola y coloca su ID de endpoint en SEEDANCE_MODEL_ID en su lugar:

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

SEEDANCE_MODEL_PROFILE solo es necesario en ese caso: un ID ep-... no dice nada sobre qué modelo está detrás, por lo que sin él, el servidor no puede validar los parámetros localmente y los pasará todos a la API para su validación.

7. Registrar con Claude Code

Desde este directorio (usa la ruta absoluta — Claude Code inicia el servidor desde directorios de trabajo arbitrarios):

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

--scope user lo hace disponible en cada proyecto. Usa --scope project para compartirlo con los colaboradores de un repositorio a través de .mcp.json, u omite --scope solo para el proyecto actual.

El servidor lee .env desde su propio directorio, por lo que no se necesitan banderas -e. Si prefieres pasar la clave explícitamente:

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. Verificación

claude mcp list

Espera una línea como:

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

Luego dentro de Claude Code, /mcp lista el servidor y sus seis herramientas. Pídele:

Lista mis tareas recientes de Seedance.

Eso prueba la autenticación y la conectividad sin gastar créditos de generación — una lista vacía es un éxito. Si la clave es incorrecta, recibirás un mensaje explícito de HTTP 401.

Para una verificación de extremo a extremo que realmente renderice un archivo, usa la receta de costo mínimo en §10.

9. Ejemplos de indicaciones para 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. Costo y tiempo

La generación se factura por segundo de salida, escalada por resolución y modelo. La forma más barata de probar que el pipeline funciona es un clip de 4 segundos a 480p — 4s es la duración más corta que acepta cualquier modelo Seedance 2.x.

Verificación gratuita, sin gastar créditos de generación:

List my recent Seedance tasks.

Generación real más barata. Seedance 2.0 mini es el modelo menos costoso en la cuenta; durante la promoción vigente hasta el 7 de septiembre de 2026, su salida a 720p comienza alrededor de 0.03 USD/segundo, y 480p está por debajo de eso:

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.

Prueba más barata de la ruta predeterminada de Seedance 2.5 — vale la pena ejecutarla por separado, ya que 2.5 es una activación de modelo diferente y un nivel de precio diferente:

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.

Línea base medida

De una ejecución real de Seedance 2.5 de texto a video el 18 de agosto de 2026:

Ese es el mínimo: la duración más corta con la resolución más baja y sin material de referencia. También establece expectativas para seedance_wait_for_video, cuyo tiempo de espera predeterminado de 900 segundos está dimensionado para trabajos un orden de magnitud más pesados que este.

Escalar a partir de esa línea base es extrapolación, no medición — el uso sigue los segundos de salida y el recuento de píxeles, por lo que un clip de 10 segundos a 1080p es aproximadamente 2.5× los segundos y ~5× los píxeles, es decir, del orden de 10× esta ejecución. Trátalo como una estimación de planificación y confírmalo con tu propia facturación.

La trampa del costo de duration

Seedance 2.5 establece duration por defecto en -1, lo que permite que el modelo elija cualquier duración de hasta 30 segundos. Dado que la facturación es por segundo de salida, una solicitud que no indique una duración puede costar alrededor de 7 veces una prueba prevista de 4 segundos. Indica el número de segundos explícitamente en cualquier ejecución sensible al costo — la herramienta lo pasa directamente, y 4 es el mínimo.

Dos notas menores: 480p y 720p están excluidas del descuento promocional actual de 2.5 (solo 1080p tiene descuento), por lo que 480p sigue siendo la más barata en términos absolutos — el descuento simplemente no se aplica. Y sin sonido principalmente acorta el tiempo de generación; nada en la documentación muestra que reduzca el precio.

11. Solución de problemas

12. Funciones compatibles de Seedance 2.5

Tipos de tarea (mutuamente excluyentes — BytePlus rechaza mezclas):

• Texto a video — solo indicación.

• Imagen a video — first_frame, opcionalmente más last_frame. La salida comienza y termina exactamente en esas imágenes.

• Referencia omni a video — hasta 30 imágenes de referencia, 10 videos de referencia y 10 clips de audio, con entrada solo de audio permitida. Cita activos en la indicación como @Image 1, @Video 2. Cubre tres subtareas: referencia a video, edición de video y extensión de video — dirígelas con omni_reference_task_type.

Controles de salida

Entradas de medios

Los prompts funcionan en inglés, español, indonesio, portugués, japonés, malayo, tailandés, árabe, vietnamita y coreano. Mantenlos por debajo de ~1000 palabras en inglés.

Guardar la salida. seedance_download_video toma un ID de tarea, busca la URL actual por sí mismo y transmite el archivo al disco. Por defecto a ./<task_id>.mp4; pasa una ruta de archivo o un directorio existente como output_path. Nunca sobrescribe sin overwrite: true, limpia archivos parciales si una descarga se interrumpe, y también puede obtener el PNG final con include_last_frame cuando la tarea se creó con return_last_frame. Dos restricciones deliberadas: las descargas se realizan a través de su propio cliente HTTP no autenticado, por lo que la clave de ModelArk nunca se envía al host de almacenamiento, y el host de la URL debe terminar en .volces.com, .bytepluses.com o .byteplus.com — este es un extractor de salida de Seedance, no un descargador de propósito general.

El servidor también apunta a modelos más antiguos mediante el argumento de herramienta model o SEEDANCE_MODEL_ID — Seedance 2.0 / 2.0 fast / 2.0 mini, 1.5 pro, 1.0 pro y 1.0 pro fast — validando cada uno contra sus propios límites (por ejemplo, 4K es válido en 2.0 pero no en 2.5).

13. Limitaciones conocidas de la API

• La generación es asíncrona. Nada devuelve un vídeo de forma síncrona; un clip de 5 a 10 segundos normalmente tarda unos minutos, más en 1080p.

• No se puede establecer seed ni camera_fixed en Seedance 2.5. La referencia actual de la API enumera ambos como parámetros de entrada solo para Seedance 1.5 pro, 1.0 pro y 1.0 pro fast. Este servidor los rechaza para 2.5 con un mensaje explícito en lugar de descartarlos silenciosamente. Expresa el comportamiento de la cámara en el prompt en su lugar. (Los tutoriales antiguos de Seedance 1.x y ejemplos de terceros aún muestran estos parámetros — ya no se aplican a 2.5.)

  Observado en una ejecución real de 2.5: la respuesta de la tarea aún informa un seed (mostrado como VideoResult.seed, p. ej. 80969), porque el modelo elige uno internamente. Así que puedes ver qué semilla produjo un clip, pero no puedes pedirla de nuevo — las generaciones de 2.5 no son reproducibles.

• No hay frames en Seedance 2.5. Las duraciones de subsegundo mediante el recuento de fotogramas son una característica de 1.0 pro.

• No se puede subir vídeo local. Las imágenes y el audio tienen una forma Base64; el vídeo no.

• Límite de 64 MB en el cuerpo de la solicitud. Incrustar varias imágenes grandes lo alcanzará; el servidor lo comprueba antes de enviar y te indica que cambies a URLs.

• Los rostros humanos reales están restringidos. Seedance 2.x rechaza imágenes de referencia y vídeos que contengan rostros humanos reales a menos que sean una salida previa de Seedance de tu propia cuenta (dentro de 30 días), un personaje digital predefinido o un activo de persona real autorizado.

• Solo se pueden cancelar las tareas en cola. Una vez que una tarea está en ejecución, se ejecuta hasta completarse.

• Las URLs de salida viven 24 horas, con un límite de 100 descargas en Seedance 2.5. Ambos límites están integrados en la propia URL firmada — un enlace devuelto lleva X-Tos-Expires=86400 y X-Tos-Max-Requests=100. No hay un punto final de reemisión, y seedance_list_tasks solo puede devolver una URL que aún esté dentro de esa ventana. Usa seedance_download_video para guardar cualquier cosa que valga la pena conservar; una vez que la ventana se cierra, el único remedio es generar de nuevo.

• Los registros de tareas viven 7 días.

• Los límites de duración de los medios de referencia no se verifican localmente. Los límites por clip (2–30 s) y total (30 s) para vídeo y audio de referencia necesitan sondeo de medios; el servidor no agrega una dependencia de decodificador para ello, por lo que BytePlus los aplica y los informa como errores de tarea.

• Los precios y las restricciones cambian. La tabla de capacidades en src/seedance_mcp/capabilities.py fue transcrita de la documentación de BytePlus el 2026-08-17; revísala si BytePlus lanza una nueva revisión del modelo.

14. Estructura del proyecto

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 y media.py son adiciones al diseño esbozado en el resumen: la tabla de restricciones por modelo documentada, el constructor de solicitudes y el manejo de medios tienen cada uno lógica real y sus propias pruebas, y fusionarlos en server.py o models.py habría hecho que ambos fueran difíciles de leer.

15. Fuentes

Cada detalle de la API anterior fue verificado con la documentación oficial actual de BytePlus:

• Crear una tarea de generación de vídeo

• Recuperar una tarea de generación de vídeo

• Listar tareas de generación de vídeo

• Cancelar o eliminar una tarea de generación de vídeo

• Tutorial de Dreamina Seedance 2.5

• Lista de modelos

• Tutorial de la API de generación de vídeo