seedance-2-5-video-generate-api-skill

Seedance 2.5 API: Text, Image, and Reference Video Skill for EvoLink

AI Agent? Run npx skills add https://github.com/Evolink-AI/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen, then read llms-install.md

[!IMPORTANT] EvoLink's official Seedance 2.5 text, image, and reference API pages currently say the models are not yet available. This repository is a schema-complete pre-integration release: dry runs, request validation, installation, and lifecycle logic work now; live generation depends on EvoLink opening the routes

📑 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 three Seedance 2.5 workflows. It understands motion, camera behavior, pacing, continuity, audio, model-specific media limits, asynchronous task handling, and the current pre-launch boundary

Installation

Agent install — recommended

npx skills add https://github.com/Evolink-AI/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/Evolink-AI/seedance-2-5-video-generate-api-skill

Manual

git clone https://github.com/Evolink-AI/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/Evolink-AI/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	Supports reference generation, editing, and extension; use @image1, @video1, @audio1 in prompts

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 for style, character, product, camera-motion, source-video, edit, extension, or audio references

Dry-run all three 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
./scripts/seedance-2-5-video-gen.sh "Extend @video1; preserve motion; use @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

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 three exact model IDs above
prompt	string	yes	Maximum 10,000 tokens
duration	integer	no	5; range 4 to 30 seconds
quality	string	no	720p; supports 480p
aspect_ratio	string	no	adaptive; also 16:9, 9:16, 1:1, 4:3, 3:4, 21:9
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 official Seedance 2.5 API pages currently mark all three routes as not yet available
• 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/Evolink-AI/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/Evolink-AI/seedance-2-5-video-generate-api-skill

Manual

git clone https://github.com/Evolink-AI/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/Evolink-AI/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-to-Video	Image-to-Video	Reference-to-Video
Prompt, camera, motion, audio, and duration become a validated text payload	One or two images become first-frame or first/last-frame video input	Images, videos, and audio become tagged reference materials for generation, edits, and extensions

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 is closed	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
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/Evolink-AI/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen
Codex	npx skills add https://github.com/Evolink-AI/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen
OpenClaw	npx skills add https://github.com/Evolink-AI/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/Evolink-AI/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen
Cursor	npx skills add https://github.com/Evolink-AI/seedance-2-5-video-generate-api-skill/tree/main/skills/seedance-2-5-video-gen

FAQ

Is Seedance 2.5 live through EvoLink? Not according to the current official API pages. The package is ready for validation and dry runs, and can execute when the routes open

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, and reference for media-guided generation, edits, or extension

What are the main input limits? Image mode accepts one or two images. Reference mode accepts up to 30 images, 10 videos, and 10 audio clips, subject to per-file, duration, and request-size limits in the official docs

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