Seedance 2.5 API Skill: Five Video Workflows for EvoLink

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

[!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

📑 Menu

• Agent Skill
• Installation
• Agent Auto-Install
• Getting an API Key
• API Quick Start
• Full First-Run Flow
• API Reference
• Showcase
• Troubleshooting
• Compatibility
• Community
• 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

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

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

openclaw skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill

Manual

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:

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
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:

./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:

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:

{
  "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
• JavaScript flow
• Python flow

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:

# 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 and references/api-params.md

Response Schema

Completed task:

{
  "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:

{
  "id": "task-unified-1774857405-abc123",
  "status": "failed",
  "error": {
    "code": "content_policy_violation",
    "message": "Content policy violation",
    "type": "task_error"
  }
}

Read the full response schema

Error Handling

All included examples check missing keys, non-2xx HTTP responses, failed task state, and polling timeout. Read 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

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

Additional Installation Examples

Agent install — recommended

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

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

openclaw skills add https://github.com/cheercheung/seedance-2-5-video-generate-api-skill

Manual

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:

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, 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, and contributions should follow CONTRIBUTING.md

Documentation

• Read the quickstart
• Read the API reference
• Understand task lifecycle
• Inspect response schemas
• Handle errors
• Implement callbacks
• Review pricing boundaries

Related Repositories

• Explore the Seedance 2.5 guide and prompt examples
• Explore Seedance 2.0 prompts

License

MIT — see LICENSE