Wan 2.7 API Guide: Text-to-Video, Image-to-Video, Reference Video & Video Edit — Complete Integration Handbook

TL;DR

• Wan 2.7 is four models in one endpoint. Text-to-video, image-to-video (with first/last frame control), multi-character reference video (with voice cloning), and instruction-based video editing — all through POST /v1/videos/generations.
• Pricing on EvoLink: $0.086/sec at 720p, $0.144/sec at 1080p. A 10-second 720p clip costs $0.86. No subscriptions.
• Model IDs: wan2.7-text-to-video, wan2.7-image-to-video, wan2.7-reference-video, wan2.7-video-edit.
• Async workflow. Every request returns a task ID immediately. Poll GET /v1/tasks/\{task_id\} for status. Video URLs expire in 24 hours.
• What Wan 2.7 adds over Wan 2.6 on EvoLink: Video editing through the Wan 2.7 route, first-and-last-frame control in I2V, and multi-character reference video with voice cloning.
• Failed tasks are not billed for reference-video and video-edit modes.

Table of contents

1. Quick start: your first Wan 2.7 video in 60 seconds
2. Choose the right model ID
3. Mode 1: Text-to-video
4. Mode 2: Image-to-video with frame control
5. Mode 3: Reference video with voice cloning
6. Mode 4: Video editing
7. Pricing and cost math
8. Async workflow and task management
9. Error handling and common status codes
10. Production patterns and guardrails
11. Migration from Wan 2.6 to Wan 2.7
12. Parameter reference cheat sheet
13. FAQ

1. Quick start: your first Wan 2.7 video in 60 seconds

Step 1: Generate a video

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-text-to-video",
    "prompt": "A drone shot over a misty mountain lake at sunrise, slow camera push forward, cinematic color grading",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

{
  "id": "task-unified-1757169743-7cvnl5zw",
  "status": "pending",
  "created": 1757169743
}

Step 2: Poll for the result

curl https://api.evolink.ai/v1/tasks/task-unified-1757169743-7cvnl5zw \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3: That's it

2. Choose the right model ID

3. Mode 1: Text-to-video

What it does

Generates a video from a text prompt. Supports optional driving audio for lip-sync or music-synced output. Auto-generates background music when no audio is provided.

Key parameters

Multi-shot narrative

Control shot structure directly in the prompt:

{
  "model": "wan2.7-text-to-video",
  "prompt": "A tense detective story. Shot 1 [0-3s] wide angle: rainy night street, neon lights. Shot 2 [3-6s] medium: detective enters old building. Shot 3 [6-9s] close-up: detective's determined eyes. Shot 4 [9-12s] medium: cautious advance through dim corridor. Shot 5 [12-15s] close-up: discovers key clue.",
  "aspect_ratio": "16:9",
  "duration": 15
}

With driving audio

{
  "model": "wan2.7-text-to-video",
  "prompt": "A cartoon general in golden armor on a horse, reciting a classical poem",
  "audio_urls": ["https://your-cdn.com/recital.mp3"],
  "duration": 10
}

4. Mode 2: Image-to-video with frame control

What it does

Three generation modes

Valid input combinations

1. image_start only
2. image_start + audio_urls
3. image_start + image_end
4. image_start + image_end + audio_urls
5. video_urls (continuation)
6. video_urls + image_end (continuation with ending frame)

Any other combination will be rejected.

Example: First-and-last-frame

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-to-video",
    "generation_mode": "first_last_frame",
    "prompt": "A product bottle rotating 360 degrees with soft studio lighting",
    "image_start": "https://your-cdn.com/bottle-front.jpg",
    "image_end": "https://your-cdn.com/bottle-back.jpg",
    "quality": "1080p",
    "duration": 5
  }'

Example: Video continuation

{
  "model": "wan2.7-image-to-video",
  "generation_mode": "video_continuation",
  "prompt": "The scene continues with the character walking toward the sunset",
  "video_urls": ["https://your-cdn.com/previous-clip.mp4"],
  "image_end": "https://your-cdn.com/sunset-ending.jpg",
  "duration": 5
}

5. Mode 3: Reference video with voice cloning

What it does

Generates new video scenes while preserving the appearance of characters from reference images or videos — and optionally cloning their voice from a short audio sample. This is how you build multi-character video series where each person looks and sounds consistent across episodes.

Key constraints

• image_urls + video_urls combined: max 5 items total
• image_start and voice audio do not count toward this 5-item limit
• Duration: 2-15 sec (image-only references), 2-10 sec (when video references are included)
• Billing: input video duration + output video duration. Failed tasks are free.

Character indexing in prompts

Reference characters by their position in the input arrays:

• English: Image 1, Image 2, Video 1, Video 2
• Chinese: 图1, 图2, 视频1, 视频2

Voice cloning: two methods

Precise key-value mapping between character references and voice audio:

{
  "model": "wan2.7-reference-video",
  "prompt": "Image 1 holds Image 2 and says: 'What lovely sunshine today'",
  "image_urls": [
    "https://your-cdn.com/girl.jpg",
    "https://your-cdn.com/toy.png"
  ],
  "model_params": {
    "voice_bindings": {
      "image1": "https://your-cdn.com/girl-voice.mp3"
    }
  },
  "duration": 10
}

Example: Multi-character brand video

{
  "model": "wan2.7-reference-video",
  "prompt": "Image 1 and Image 2 are having a conversation in a modern office. Image 1 explains the product while Image 2 takes notes. The scene is professional and well-lit.",
  "image_urls": [
    "https://your-cdn.com/spokesperson-a.jpg",
    "https://your-cdn.com/spokesperson-b.jpg"
  ],
  "image_start": "https://your-cdn.com/office-wide-shot.jpg",
  "model_params": {
    "voice_bindings": {
      "image1": "https://your-cdn.com/voice-a.mp3",
      "image2": "https://your-cdn.com/voice-b.mp3"
    }
  },
  "quality": "1080p",
  "duration": 10
}

Multi-grid storyboard

For single-image references with multiple panels (e.g., a 3×3 grid of character poses):

{
  "model": "wan2.7-reference-video",
  "prompt": "Reference image. 3D cartoon style. 1. Wide shot of fantasy forest. 2. Boy parts the vines. 3. Robot scans ahead. 4. Close-up of map. 5. Boy's excited face. 6. They leap over roots.",
  "image_urls": ["https://your-cdn.com/storyboard-grid.png"],
  "duration": 15
}

6. Mode 4: Video editing

What it does

Key parameters

Example: Instruction-only style change

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video-edit",
    "prompt": "Convert the entire scene to a vintage film look with warm color grading and film grain",
    "video_urls": ["https://your-cdn.com/source-clip.mp4"],
    "keep_original_sound": true,
    "duration": 0
  }'

Example: Reference-guided clothing replacement

{
  "model": "wan2.7-video-edit",
  "prompt": "Replace the girl's outfit with the clothes from the reference image",
  "video_urls": ["https://your-cdn.com/source.mp4"],
  "image_urls": ["https://your-cdn.com/target-outfit.png"]
}

What you can edit

• Style transfer: "convert to anime style", "apply watercolor painting effect"
• Background swap: "change background to a rain-soaked Tokyo street at night"
• Object/clothing change: "swap the jacket to red", "replace the hat with a crown"
• Colorization: "convert this black-and-white footage to color"
• Lighting: "shift lighting to golden hour"

7. Pricing and cost math

EvoLink Wan 2.7 pricing

No subscriptions, no minimum commitments. You pay only for successfully generated video.

Cost comparison with other providers (as listed on provider pages, May 2026)

Special billing for reference-video and video-edit

Budget estimation formula

8. Async workflow and task management

Every Wan 2.7 request follows the same async pattern:

Task lifecycle

Callback URL (webhook)

Production best practices

1. Persist the task ID immediately after submission. If your service crashes, you can recover.
2. Use exponential backoff when polling. Start at 5 seconds, cap at 30 seconds.
3. Download and archive results immediately. Video URLs expire in 24 hours.
4. Make submissions idempotent. Hash request payloads and deduplicate to prevent double-billing from retry storms.

9. Error handling and common status codes

Common mistakes

• Using the wrong model ID spelling. It's wan2.7-text-to-video, not wan-2.7-text-to-video or wan27-t2v. A stale model ID returns a clean 404 with no helpful error.
• Sending invalid media combinations in I2V mode. Check the valid input combinations table.
• Not downloading results in time. Video URLs expire in 24 hours. Build automatic download into your pipeline.

10. Production patterns and guardrails

Budget guardrails

Reliability patterns

• Retry with idempotency key. Hash your request payload and check for existing tasks before resubmitting.
• Timeout handling. If a task hasn't completed after 5 minutes, mark it for manual review rather than resubmitting blindly.
• Fallback strategy. Consider falling back to Wan 2.6 or Wan 2.5 if Wan 2.7 returns persistent errors on a specific mode.
• Asset validation. Validate image dimensions, video duration, and audio format before submission. Bad assets cause failures that look like model quality issues.

Queue architecture

For production systems generating more than 100 videos/day:

Never call the API directly from user-facing request handlers. Always go through a background job system.

11. Migration from Wan 2.6 to Wan 2.7

What stays the same

• API endpoint: POST /v1/videos/generations
• Authentication: same API key and Bearer token
• Async pattern: same task ID / polling / callback flow
• EvoLink billing: same account and credit system

What changes

Step-by-step migration

1. Change model parameter. Replace wan2.6-text-to-video with wan2.7-text-to-video (same for other modes).
2. Test with existing prompts. Wan 2.7 handles the same prompt format. No rewriting needed.
3. Adopt new features gradually. Add generation_mode, image_end, voice_bindings, or video-edit as your workflow requires.
4. Keep Wan 2.6 as fallback. Both versions run in parallel on EvoLink. You don't have to migrate everything at once.

12. Parameter reference cheat sheet

Shared parameters (all modes)

Text-to-video specific

Image-to-video specific

Reference video specific

Video edit specific

13. FAQ

How much does Wan 2.7 cost on EvoLink?

$0.086/sec at 720p, $0.144/sec at 1080p. A 10-second 720p clip costs $0.86. No subscriptions or minimum commitments.

What is the difference between Wan 2.7 and Wan 2.6?

On EvoLink, Wan 2.7 exposes video editing, multi-character reference video with voice cloning, and first-and-last-frame control in I2V mode. Wan 2.6 remains useful for cinematic storytelling and Flash variants for faster iteration. Both run in parallel on EvoLink.

Does Wan 2.7 generate audio automatically?

Are failed tasks billed?

For reference-video and video-edit modes, failed tasks are explicitly not billed. For text-to-video and image-to-video, billing is based on actual generated video duration.

Can I use Wan 2.7 for NSFW content?

What audio formats are supported for voice cloning?

How do I handle video URL expiration?

Video URLs expire after 24 hours. Build an automatic download-and-archive step into your pipeline immediately after task completion. Store the final asset in your own CDN or object storage.

Can I migrate from Wan 2.6 without downtime?

Next steps

• Try the playground: Wan 2.7 model page
• Compare Wan models: Wan API family collection
• Full pricing breakdown: Wan API pricing guide
• Wan 2.6 production patterns: Wan 2.6 API guide
• Wan 2.5 review: Wan 2.5 API review