# Seedance 2.5 API Skill: Five Video Workflows for EvoLink

Build validated Seedance 2.5 video requests, install the agent skill, and run the complete asynchronous EvoLink workflow from task creation to final video URL

Menu · Install · API Reference · Showcase · Troubleshooting

English · Español · Português · 日本語 · 한국어 · Deutsch · Français · Türkçe · 繁體中文 · 简体中文 · Русский

> **AI Agent? Skip the README.** Run `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen`, then read [llms-install.md](llms-install.md) > [!IMPORTANT] > The latest official overview documents five separate model IDs: Text-to-Video, Image-to-Video, Reference-to-Video, Video Edit, and Video Extend. Run `--check-availability`, validate account access, preview the exact payload, and confirm the cost boundary before a live task

View Seedance 2.5 availability and pricing · Get your EvoLink API key · Read Seedance 2.5 API docs

## 📑 Menu - [Agent Skill](#agent-skill-first) - [Installation](#installation) - [Agent Auto-Install](#agent-auto-install) - [Getting an API Key](#getting-an-api-key) - [API Quick Start](#api-quick-start) - [Full First-Run Flow](#full-first-run-flow) - [API Reference](#api-reference) - [Showcase](#showcase) - [Troubleshooting](#troubleshooting) - [Compatibility](#compatibility) - [Community](#community) - [License](#license) ## Agent Skill The `seedance-2-5-video-gen` skill converts user intent into time-aware prompts and validated requests for all five Seedance 2.5 workflows. It understands motion, camera behavior, pacing, continuity, audio, model-specific media limits, asynchronous task handling, and paid-task approval boundaries ## Installation ### Agent install — recommended ```bash npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen ``` ### npm fallback and direct CLI ```bash npx evolink-seedance-2-5@latest -y --path ~/.claude/skills npx evolink-seedance-2-5@latest "A five-second studio product shot" --mode text --dry-run ``` ### OpenClaw ```bash openclaw skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill ``` ### Manual ```bash git clone https://github.com/cheercheung/seedance-2-5-video-generate-api-skill.git cd seedance-2-5-video-generate-api-skill node bin/cli.js -y --path ~/.claude/skills --no-open ``` ### Agent Auto-Install Copy this to Claude Code, Codex, OpenClaw, OpenCode, or Cursor: ```text Install the Seedance 2.5 skill by running: npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen Then read the installed SKILL.md, check official availability, and run a text-to-video dry run before making any real API call ``` ## Getting an API Key 1. [Open the EvoLink API key page](https://evolink.ai/dashboard/keys?utm_source=npm&utm_medium=package&utm_campaign=seedance-2-5-video-gen) 2. Sign in or sign up and return to the key page 3. Create or select a key, then export it as `EVOLINK_API_KEY` 4. Validate it through the non-generating credits endpoint before any generation task The installer exposes `EVOLINK_KEY_URL`, `AGENT_NEXT_ACTION`, and `ENV_VAR_EXPORT` so an Agent can complete the handoff safely. The credits endpoint does not create a generation task --- ## Quick Start Preview a valid text-to-video request without an API key or credit spend: ```bash ./scripts/seedance-2-5-video-gen.sh \ "A paper airplane crosses a sunlit studio; the camera pans smoothly to follow it; it lands centered on a wooden desk; quiet room ambience" \ --mode text --duration 5 --aspect-ratio 16:9 --dry-run ``` The live create request uses: ```bash export EVOLINK_API_KEY="your_key_here" curl --request POST \ --url https://api.evolink.ai/v1/videos/generations \ --header "Authorization: Bearer ${EVOLINK_API_KEY}" \ --header "Content-Type: application/json" \ --header "X-EvoLink-Source: skill" \ --header "X-EvoLink-Skill: seedance-2-5-video-gen" \ --header "X-EvoLink-Package: evolink-seedance-2-5" \ --header "X-EvoLink-Campaign: seedance-2-5-video-gen" \ --header "X-EvoLink-Touchpoint: first_call" \ --data '{ "model": "seedance-2.5-text-to-video", "prompt": "A paper airplane crosses a sunlit studio; smooth tracking pan; it lands centered on a wooden desk", "duration": 5, "quality": "720p", "aspect_ratio": "16:9", "output_format": "mp4", "generate_audio": true, "content_filter": true }' ``` Pending response shape: ```json { "created": 1761313744, "id": "task-unified-1774857405-abc123", "model": "seedance-2.5-text-to-video", "object": "video.generation.task", "progress": 0, "status": "pending", "type": "video", "task_info": { "can_cancel": true, "estimated_time": 165, "video_duration": 5 } } ``` ## Full First-Run Flow 1. Validate the key without generating: `GET /v1/credits` 2. Create a task: `POST /v1/videos/generations` 3. Store the returned `id` 4. Poll `GET /v1/tasks/{task_id}` until `completed` or `failed`, or use `callback_url` 5. Read the final URLs from `results` 6. Save the files promptly because generated URLs may expire Runnable complete flows: - [cURL and shell flow](examples/curl/complete-flow.sh) - [JavaScript flow](examples/javascript/complete-flow.mjs) - [Python flow](examples/python/complete_flow.py) ## API Reference The family shares one create endpoint and one task endpoint, while each model ID enforces different media inputs ## Supported Models and Workflows | Workflow | Model ID | Required media | Special behavior | |---|---|---|---| | Text-to-Video | `seedance-2.5-text-to-video` | None | Supports `model_params.web_search`; rejects media arrays | | Image-to-Video | `seedance-2.5-image-to-video` | One or two image URLs | One image is the first frame; two images are first and last frames | | Reference-to-Video | `seedance-2.5-reference-to-video` | At least one image, video, or audio URL | Generates new footage from references; edit/extend intent must use dedicated modes | | Video Edit | `seedance-2.5-video-edit` | One to ten video URLs | First video is edit target; `duration=-1`; `aspect_ratio=adaptive` | | Video Extend | `seedance-2.5-video-extend` | One to ten video URLs | First video is extension target; `duration=-1` or 4–30; `aspect_ratio=adaptive` | ## Choose the Right Workflow - Use **text** when the shot can be described without input media - Use **image** to animate one image or interpolate between first and last frames - Use **reference** to generate new footage from style, character, product, camera-motion, video, or audio references - Use **edit** to alter an existing video's content while following its source duration - Use **extend** to continue an existing video forward or backward Dry-run all five routes: ```bash # Text ./scripts/seedance-2-5-video-gen.sh "A red shirt rotates once in a white studio" --mode text --duration 5 --dry-run # Image ./scripts/seedance-2-5-video-gen.sh "Subtle premium push-in; preserve the bottle" --mode image --image-url https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1200 --dry-run # Reference generation ./scripts/seedance-2-5-video-gen.sh "Generate a new shot using @video1 for camera motion and @audio1 as music" --mode reference --video-url https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4 --audio-url https://samplelib.com/lib/preview/mp3/sample-3s.mp3 --duration 8 --dry-run # Video edit ./scripts/seedance-2-5-video-gen.sh "Edit @video1: replace the cup while preserving camera motion" --mode edit --video-url https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4 --duration -1 --dry-run # Video extend ./scripts/seedance-2-5-video-gen.sh "Extend @video1 forward with the same camera and subject motion" --mode extend --video-url https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4 --duration 8 --dry-run ``` ## Endpoints | Purpose | Method | Endpoint | |---|---|---| | Validate key and read credits | `GET` | `https://api.evolink.ai/v1/credits` | | Create video task | `POST` | `https://api.evolink.ai/v1/videos/generations` | | Query task | `GET` | `https://api.evolink.ai/v1/tasks/{task_id}` | ## Request Parameters Shared fields: | Field | Type | Required | Default / limit | |---|---|---:|---| | `model` | string | yes | One of the five exact model IDs above | | `prompt` | string | yes | Maximum 10,000 tokens | | `duration` | integer | no | `-1` or 4 to 30; Edit accepts only `-1` | | `quality` | string | no | `720p`; supports `480p` | | `aspect_ratio` | string | no | Text/Reference accept fixed ratios or `adaptive`; Image/Edit/Extend accept only `adaptive` | | `output_format` | string | no | `mp4`; also `mov` | | `generate_audio` | boolean | no | `true` | | `content_filter` | boolean | no | `true`; disabling it is documented as a 1.1x billing multiplier | | `callback_url` | string | no | HTTPS only; no private network targets | Media fields and limits are documented in [docs/api-reference.md](docs/api-reference.md) and [references/api-params.md](references/api-params.md) ## Response Schema Completed task: ```json { "id": "task-unified-1774857405-abc123", "model": "seedance-2.5-text-to-video", "object": "video.generation.task", "progress": 100, "status": "completed", "type": "video", "results": ["https://cdn.evolink.ai/results/task-id/video.mp4"] } ``` Failed task: ```json { "id": "task-unified-1774857405-abc123", "status": "failed", "error": { "code": "content_policy_violation", "message": "Content policy violation", "type": "task_error" } } ``` Read the full [response schema](docs/response-schema.md) ## Error Handling All included examples check missing keys, non-2xx HTTP responses, failed task state, and polling timeout. Read [docs/errors.md](docs/errors.md) for common corrections ## Callback and Webhook Set `callback_url` to an HTTPS endpoint to receive the final task object after completion, failure, or cancellation. EvoLink documents a 10-second callback timeout and retries after 1, 2, and 4 seconds. Read [docs/callbacks.md](docs/callbacks.md) ## Pricing and Availability - The latest official overview documents all five variants; live access can still depend on account and backend availability - This repository does not assert a numeric live price - Duration affects billing; reference video inputs can add billed input duration - `content_filter=false` is documented as a 1.1x multiplier - Treat the live `usage` object, EvoLink model page, and dashboard as the source of truth [View current Seedance 2.5 availability and pricing](https://evolink.ai/seedance-2-5?utm_source=npm&utm_medium=package&utm_campaign=seedance-2-5-video-gen) ## Additional Installation Examples ### Agent install — recommended ```bash npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen ``` ### npm fallback and direct CLI ```bash npx evolink-seedance-2-5@latest -y --path ~/.claude/skills npx evolink-seedance-2-5@latest "A five-second studio product shot" --mode text --dry-run ``` ### OpenClaw ```bash openclaw skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill ``` ### Manual ```bash git clone https://github.com/cheercheung/seedance-2-5-video-generate-api-skill.git cd seedance-2-5-video-generate-api-skill node bin/cli.js -y --path ~/.claude/skills --no-open ``` ## Agent Skill Usage Examples Copy this to Claude Code, Codex, OpenClaw, OpenCode, or Cursor: ```text Install the Seedance 2.5 skill by running: npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen Then read the installed SKILL.md, check official availability, and run a text-to-video dry run before making any real API call ``` The installer prints `EVOLINK_KEY_URL`, `AGENT_NEXT_ACTION`, and persistent `EVOLINK_API_KEY` guidance ## 🖼️ Showcase | Text / Image | Reference | Edit / Extend | |---|---|---| | Text prompts or one/two frames become a validated generation payload | Images, videos, and audio guide the creation of new footage | Dedicated models modify or continue the first input video with strict duration and aspect-ratio rules | ## Production Notes - Run `./scripts/seedance-2-5-video-gen.sh --check-availability` before enabling a live call - Run `--validate-key` before the first generation request - Never resubmit automatically after a task ID has been returned - Use `X-EvoLink-Touchpoint: first_call` once, then `subsequent_call` - Persist task IDs and download final outputs promptly - Use callbacks for production systems; validate webhook authenticity through your own secret or network controls - Keep `content_filter=true` unless you understand the billing and safety consequences ## Troubleshooting | Issue | Fix | |---|---| | Official route or account access is unavailable | Use `--dry-run` and the availability probe; do not fabricate a result | | `EVOLINK_API_KEY` is missing | [Get an EvoLink API key](https://evolink.ai/dashboard/keys?utm_source=npm&utm_medium=package&utm_campaign=seedance-2-5-video-gen), then export it | | Image mode has no image | Pass one or two `--image-url` values | | Reference mode has no media | Pass at least one `--image-url`, `--video-url`, or `--audio-url` | | Edit or extend mode has no target | Pass at least one `--video-url`; the first video is the target | | Edit mode uses a custom duration | Use `--duration -1`; edit follows the input video's timeline | | Image, edit, or extend uses a fixed ratio | Use `--aspect-ratio adaptive` | | Task times out locally | Keep the task ID and query it later; do not resubmit blindly | | API returns `401` or `403` | Validate the key and model access with the current account | | API returns `429` or `5xx` | Back off and retry only within an approved cost boundary | ## Compatibility | Agent | Preferred install | |---|---| | Claude Code | `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen` | | Codex | `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen` | | OpenClaw | `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen` or OpenClaw CLI | | OpenCode | `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen` | | Cursor | `npx skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen` | ## FAQ **Is Seedance 2.5 live through EvoLink?** The latest official documentation exposes all five API variants. Use `--check-availability` plus key/account validation before treating any route as production-accessible **How does billing work?** Duration affects billing, reference videos can add input-duration cost, and disabling the content filter is documented as a 1.1x multiplier. Use the live `usage` object and dashboard for current totals **How long do result URLs last?** EvoLink task documentation says generated media URLs can expire. Save completed outputs promptly **Can I use callbacks instead of polling?** Yes. Supply an HTTPS `callback_url` **Which workflow should I choose?** Use text with no media, image for first or first/last frames, reference for generating new footage from media, edit for altering an existing video, and extend for continuing one **What are the main input limits?** Image mode accepts one or two images. Reference accepts up to 30 images, 10 videos, and 10 audio clips. Edit and Extend require 1–10 videos and allow supplementary image/audio references, subject to the official per-file, duration, and request-size limits ## Community Use GitHub issues for API bugs and documentation corrections. Security reports should follow [SECURITY.md](SECURITY.md), and contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md) ## Documentation - [Read the quickstart](docs/quickstart.md) - [Read the API reference](docs/api-reference.md) - [Understand task lifecycle](docs/task-lifecycle.md) - [Inspect response schemas](docs/response-schema.md) - [Handle errors](docs/errors.md) - [Implement callbacks](docs/callbacks.md) - [Review pricing boundaries](docs/pricing.md) ## Related Repositories - [Explore the Seedance 2.5 guide and prompt examples](https://github.com/Evolink-AI/awesome-seedance-2.5-guide) - [Explore Seedance 2.0 prompts](https://github.com/Evolink-AI/awesome-seedance-2.0-prompts) ## License MIT — see [LICENSE](LICENSE)