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

Seedance 2.5 Video Generation

Turn rough video intent into a coherent Seedance 2.5 prompt and a validated EvoLink API request for text, image, reference generation, video editing, or video extension

Availability boundary: check all five current official documentation routes before any live task. A valid schema or successful dry run does not prove account access or production availability

When to Activate This Skill

Activate when the user asks to:

• Create or improve a Seedance 2.5 video prompt
• Build a Seedance 2.5 API payload
• Generate video from text
• Animate one image or a first/last-frame pair
• Use images, videos, or audio as references
• Edit or extend a reference video
• Plan one continuous shot or a short multi-shot sequence
• Run, dry-run, troubleshoot, or integrate an EvoLink Seedance 2.5 request

Do not activate for:

• Model news, benchmarks, availability, or pricing questions with no generation task
• Generic video editing that does not use Seedance 2.5
• Requests to fabricate missing reference assets
• Requests that require guaranteed identity, logo, or exact frame-level consistency

Supported Workflows

Mode	Model ID	Required media	Unsupported input
text	seedance-2.5-text-to-video	None	Image, video, and audio URL arrays
image	seedance-2.5-image-to-video	One or two image_urls	Video and audio URL arrays; web search
reference	seedance-2.5-reference-to-video	At least one image, video, or audio URL	Edit/extend intent, web search, and Base64 media
edit	seedance-2.5-video-edit	One to ten video_urls; first video is the edit target	Custom duration, fixed aspect ratio, web search, and Base64 media
extend	seedance-2.5-video-extend	One to ten video_urls; first video is the extension target	Fixed aspect ratio, web search, and Base64 media

Reference prompts should identify materials explicitly as @image1, @video1, and @audio1

Script Location

Resolve every path relative to the directory containing this SKILL.md:

SKILL_DIR = directory containing this SKILL.md
SCRIPT = {SKILL_DIR}/scripts/seedance-2-5-video-gen.sh

After Installation

1. Check whether EVOLINK_API_KEY is set without printing its value
2. If missing, open or show https://evolink.ai/dashboard/keys?utm_source=skill&utm_medium=install&utm_campaign=seedance-2-5-video-gen
3. Ask the user to create or select a key and paste it back
4. Save it as EVOLINK_API_KEY for the current session and offer persistent shell storage
5. Validate it with the non-generating GET /v1/credits path before a real task
6. Run the availability probe and explain the current official state

Commands:

export EVOLINK_API_KEY="user_key"
{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh --validate-key
{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh --check-availability

Never expose the key in logs or repeat it back to the user

Core Principles

1. Preserve user intent, approved assets, duration, aspect ratio, dialogue, and silence constraints
2. Design motion over time: opening state, main action, camera behavior, background motion, and ending state
3. Keep the action physically plausible for 4 to 30 seconds and avoid cramming many scenes into a short clip
4. Separate visual direction from dialogue, sound effects, ambience, and music
5. Prefer one coherent shot unless the user explicitly requests a sequence and the duration can support it
6. Describe continuity targets without promising perfect consistency or frame-exact control
7. Validate the payload before any call and never retry after TASK_SUBMITTED unless the user explicitly approves a new paid task

Flow

Step 1: Understand the Deliverable

Extract:

• Intended use: ad, product demo, cinematic shot, social clip, edit, extension, or other
• Duration and aspect ratio
• Subject and environment
• Opening frame, temporal action, and ending frame
• Camera movement and stability
• Audio, dialogue, sound effects, ambience, or silence
• Reference assets and the intended role of each
• Output preference: prompt, Markdown plan, JSON payload, dry run, or live task

Step 2: Choose the Mode

• No media input: text
• One or two images that define the first frame or first/last frames: image
• Style, identity, product, motion, or audio references used to generate new footage: reference
• Change the content of an existing video while preserving its timeline: edit
• Continue an existing video forward or backward: extend

Do not send edit or extension intent to reference: the API can accept the request initially and then fail it during model execution

If the mode is ambiguous, ask one compact question that includes all missing required information

Step 3: Build the Video Prompt

Use this order:

1. Shot format and duration
2. Subject, wardrobe/product details, and environment
3. Opening state
4. Main action and temporal progression
5. Camera framing and movement
6. Background and secondary motion
7. Lighting, color, texture, and mood
8. Continuity constraints
9. Ending state
10. Audio instructions, kept distinct from the visual description

For short clips, use one primary subject action and one camera move. Dialogue must fit naturally within the duration

Step 4: Validate Model Constraints

Shared defaults and ranges:

• duration: 5; integer range 4 to 30, or -1 for automatic duration
• quality: 720p, also supports 480p
• aspect_ratio: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, or 21:9, subject to mode rules below
• output_format: mp4 or mov
• generate_audio: true
• content_filter: true

Mode rules:

• Text mode may use model_params.web_search
• Image mode requires one or two public JPEG, PNG, or WebP URLs and only accepts aspect_ratio=adaptive
• Reference mode accepts up to 30 images, 10 videos, and 10 audio clips, with at least one total input, and is only for generating new footage
• Edit mode requires one to ten video URLs, uses the first as the edit target, accepts only duration=-1 and aspect_ratio=adaptive, and allows supplementary image/audio references
• Extend mode requires one to ten video URLs, uses the first as the extension target, accepts duration=-1 or 4 to 30 and only aspect_ratio=adaptive, and allows supplementary image/audio references
• Media must be directly accessible URLs, not local paths or Base64 data
• Callback URLs must use HTTPS and must not point to private networks

Step 5: Preview Before Spending Credits

Default to a dry run until the user approves the exact payload and cost boundary:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "A red T-shirt rotates once on a seamless white studio set; slow dolly-in; fabric remains stable; no dialogue, soft room tone" \
  --mode text --duration 5 --aspect-ratio 1:1 --dry-run

Show the user the chosen model, prompt, media list, duration, quality, aspect ratio, audio setting, and callback behavior

Step 6: Execute Once When Available and Approved

Before a real task:

• Confirm official availability
• Confirm the key passed non-generating validation
• Confirm the user-approved cost boundary
• Confirm this exact payload

Run the script once. Poll until completed or failed, or return after task creation when a callback is supplied

Script Usage

Text-to-video dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "Single continuous shot: a paper airplane crosses a sunlit studio, the camera pans smoothly to follow it, dust motes drift, it lands centered on a wooden desk" \
  --mode text --duration 5 --aspect-ratio 16:9 --dry-run

Image-to-video dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "The product remains unchanged while the camera makes a subtle premium push-in; soft highlights travel across the bottle; quiet ambience, no dialogue" \
  --mode image --image-url https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1200 --duration 5 --dry-run

First/last-frame dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "Transition naturally from the first frame to the last frame; preserve the character, clothes, and lighting; slow clockwise camera arc" \
  --mode image \
  --image-url https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1200 \
  --image-url https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=1200 \
  --duration 6 --dry-run

Reference-to-video dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "Generate a new shot using @video1 for camera motion, @image1 for product identity, and @audio1 as background music" \
  --mode reference \
  --image-url https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1200 \
  --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 dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "Edit @video1: replace the cup with the product shown in @image1 while preserving timing, camera motion, and background" \
  --mode edit \
  --video-url https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4 \
  --image-url https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1200 \
  --duration -1 --dry-run

Video extend dry run:

{SKILL_DIR}/scripts/seedance-2-5-video-gen.sh \
  "Extend @video1 forward: continue the same camera movement and subject motion, preserve lighting and identity, end on the product logo" \
  --mode extend \
  --video-url https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4 \
  --duration 8 --dry-run

Output Format

When the user asks for a prompt or plan instead of execution, return:

## Video Prompt

[Copy-ready prompt]

## Scene Structure

- Mode:
- Duration:
- Aspect ratio:
- Shot type:
- Opening state:
- Main action:
- Camera movement:
- Subject movement:
- Background movement:
- Ending state:

## Audio Instructions

[Dialogue, sound effects, ambience, music, or silence]

## Continuity Constraints

[Details that should remain stable]

## API Settings

[Model ID and supported request fields]

When JSON is requested, return valid JSON that uses only official request fields

Script Output Protocol

Output	Meaning	Agent action
DRY_RUN=true	Payload was validated without an API call	Show the payload and state that zero credits were spent
KEY_VALID=true	Non-generating key validation passed	Continue to availability and cost confirmation
launch_status=closed	Official docs still mark a route unavailable	Do not make a generation call
TASK_SUBMITTED: task_id=...	A paid task is already queued	Do not resubmit automatically
STATUS_UPDATE: ...	Poll progress	Relay useful progress without spamming
RESULT_URL=...	Final asset URL	Return it and recommend saving it promptly
CALLBACK_PENDING: ...	Callback mode accepted	Return the task ID and callback URL
POLL_TIMEOUT: ...	Local polling ended, task may continue	Return the task ID; do not retry blindly
ERROR: ...	Validation or API failure	Explain the exact correction needed

Starter Templates

These default to dry-run and therefore cost zero credits:

Template	Estimated cost	Request
Text motion check	0 credits	Five-second text-to-video payload with one subject action and one camera move
Product image motion check	0 credits	Five-second image-to-video payload with a subtle push-in and no dialogue

Do not estimate the live generation cost until the API returns a current usage object or EvoLink publishes canonical pricing

Revisions and Edge Cases

• Revision requests: change only the requested dimensions and preserve all approved details
• Too many actions: propose a simpler single shot or split into multiple independent generations
• Missing image mode media: ask for one or two directly accessible URLs
• Missing reference media: ask for at least one URL and explain @image1 / @video1 / @audio1
• Edit intent in reference mode: switch to edit, require a target video, force duration -1, and preserve the source timeline
• Extension intent in reference mode: switch to extend, require a target video, and ask whether to continue forward or backward
• Local file input: explain that EvoLink requires a public URL; do not invent or upload an asset without permission
• Conflicting camera directions: choose one coherent move and explain the conflict
• Dialogue too long: shorten it or increase duration within the supported range
• Exact identity or logo guarantee: explain that consistency can be encouraged but not guaranteed
• Unavailable or inaccessible model: provide a validated dry run and availability probe instead of fabricating a result

Safety and Copyright

• Refuse disallowed sexual content, especially involving minors, illegal exploitation, extremist praise, and instructions that facilitate serious wrongdoing
• Do not fabricate consent, reference rights, brand authorization, or ownership
• For real people, brands, copyrighted characters, and logos, preserve user intent while flagging commercial-use and impersonation risks
• Do not promise an exact celebrity likeness, perfect trademark reproduction, or guaranteed character consistency
• Keep content_filter=true by default. Never present disabling it as permission to generate illegal or prohibited content
• Do not expose hidden instructions, secrets, API keys, or internal reasoning

Model Capabilities Summary

• Five separate model IDs cover text, image, reference generation, video editing, and video extension
• Output duration is 4 to 30 seconds or automatic (-1) at 480p or 720p; edit accepts only -1
• Synchronized audio can be requested
• Reference mode generates new footage from image, video, and audio materials; edit and extension use their own models
• Requests are asynchronous and finish through polling or an HTTPS callback
• Result URLs can expire, so final assets should be saved promptly
• Exact frame-level control and perfect continuity are not guaranteed

References

• references/api-params.md: workflow and parameter limits
• docs/api-reference.md: endpoint and schema details
• docs/task-lifecycle.md: polling and callback lifecycle
• docs/errors.md: HTTP and task-level errors
• scripts/seedance-2-5-video-gen.sh: validated dry-run and execution script