Seedance 1.5 Pro API Integration via EvoLink: Async Tasks, Callbacks & Modes

What you’ll learn

• Ship Seedance 1.5 Pro via EvoLink’s async Task API (create → status → results).
• Use callback_url safely (HTTPS-only, retry semantics, and failure handling).
• Use one endpoint for text-to-video, image-to-video, and first-last-frame.
• Prevent double-processing with idempotency keys and retry budgets.
• Re-host outputs before links expire (24-hour retention window).
• Model “cost per successful output” without relying on fragile pricing snapshots.
• Compare integration tradeoffs vs Veo 3.1 and Kling O1 (shape-based, not price-based).

Quickstart checklist (copy/paste into your ticket)

• Implement POST /v1/videos/generations to create tasks
• Implement GET /v1/tasks/{task_id} polling
• Implement callback_url endpoint (2xx fast + async processing)
• Add idempotency key per user intent (“Generate” click)
• Re-host video assets within 24 hours
• Instrument: p50/p95 latency, policy failure rate, retry rate, attempts-per-success

EvoLink API contract (what you actually ship)

• Create a task → receive task_id
• Either poll GET /v1/tasks/{task_id} or receive a callback at callback_url
• On completion, retrieve results URLs and download immediately (links expire)

Endpoint overview

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• Output links are valid for 24 hours. Re-host promptly.

One endpoint, three modes (mode detection via image_urls)

• 0 images → text-to-video
• 1 image → image-to-video
• 2 images → first-last-frame (first frame + last frame guidance)

• Max 2 images per request
• Each image ≤ 10MB
• Formats: jpg/jpeg/png/webp
• URLs must be directly accessible by the server

Request fields that matter in production

These are the parameters you’ll actually operationalize:

• model: use "seedance-1.5-pro"
• prompt (required): up to 2000 tokens
• duration: default 5s; supported 4–12s

  Operational note: billing scales with duration; treat duration as a first-class budget lever.

• quality: 480p or 720p (default 720p)
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (default 16:9)
• generate_audio: boolean (default true)

  Tip: put dialogue in double quotes to improve spoken lines.

• callback_url: HTTPS-only callback URL for completed/failed/cancelled tasks (recommended)

Parameter defaults by scenario (fast decisions)

Task lifecycle: design your state machine first

A reliable integration starts with a predictable internal state machine:

created → queued/processing → succeeded → (download → rehost → delivered)
                     └──────→ failed (policy | transient | internal)
                     └──────→ cancelled

Minimal working examples (EvoLink)

1) Create a task (cURL) — copy/paste safe

This example avoids shell-escaping pitfalls by using a prompt without apostrophes.

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://your-domain.com/webhooks/evolink-task"
  }'

The API returns immediately with a task object containing at least:

• id (task id)
• status
• usage fields (e.g., billing_rule, credits_reserved)

2) Poll task status (cURL)

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <token>'

When completed, the task includes:

• results array with output URLs
• status and progress

callback_url: reliability rules (do not skip)

• HTTPS only
• Internal/private network IPs blocked
• Timeout: 10 seconds
• Max 3 retries with backoff at 1 / 2 / 4 seconds
• Callback body aligns with task query response format

Callback production checklist (copy/paste)

• Respond 2xx within 200ms–500ms (enqueue work; don't do heavy work inline)
• Validate task_id exists and belongs to your tenant/user
• Immediately re-query GET /v1/tasks/{task_id} before marking final state
• Deduplicate callbacks (store task_id + final status; ignore repeats)
• Log raw callback payload for debugging (redact secrets)
• Alert when callback failure rate increases (usually indicates your endpoint issues)

Idempotency: prevent double-processing (and "pay twice" behavior)

Even if your provider is correct, your system can still create duplicates because:

• Users double-click "Generate"
• Mobile networks retry
• Gateways time out

• Client generates idempotency_key per user intent (one click = one key)
• Server stores (user_id, idempotency_key) → task_id with TTL
• On repeats, return the same task_id instead of creating a new task

Don't assume idempotency is "handled for you" unless the API explicitly documents it. Implement it at your application edge.

Asset delivery: the 24-hour trap

Since output links expire in 24 hours, your pipeline should:

• Download the result immediately when status=completed
• Re-host in your object storage (S3/GCS/R2)
• Serve via CDN
• Persist metadata: task_id, prompt hash, user id, duration, quality, audio flag, moderation outcome category

Prevent it by re-hosting automatically on completion.

Cost modeling without price snapshots (still actionable)

Even if you never publish pricing numbers, you still need a durable unit economics model.

1) Know what the platform bills on

Operationally, your spend is driven by:

• duration (longer clip → more expensive)
• generate_audio (audio adds cost)
• Iteration (users rarely get it right the first time)

2) Budget "cost per successful output," not "cost per attempt"

Track:

• attempts_per_success (by scenario)
• retry_rate
• policy_failure_rate
• p95_latency

Then your real unit:

successful outputs per session × average attempts needed

3) Draft → Approve → Final (most reliable spend reducer)

When you see high iteration:

• Draft using cheaper settings (e.g., lower quality/shorter duration) or a cheaper tier/model
• Finalize with Seedance 1.5 Pro (with audio) only after user approves

No fixed % promises—just a predictable strategy that improves with iteration-heavy usage.

Production pitfalls & solutions

1) The async trap (timeouts + zombie jobs)

• Set a "job TTL" and a "still processing" UI state
• Track p95 completion time; degrade gracefully when it spikes

2) Moderation outcomes can arrive late

Design UI/backend states for "failed after processing."

• Separate: policy vs transient vs internal
• Never auto-retry policy failures
• Provide prompt rewrite guidance (especially around sensitive content)

3) Storage is part of your API

Binary is heavy:

• Don't stream through your gateway
• Download → store → CDN

Comparison: Seedance 1.5 Pro vs Veo 3.1 vs Kling O1 (no price snapshots)

Numbers age fast. Compare what lasts: accounting shape, integration surface, and workflow fit.

Table A — Integration & accounting shape

Table B — Production decision matrix

Decision checklist (fast yes/no)

• You need native audio and can structure dialogue in quotes
• You need text-to-video + image-to-video + first-last-frame under one contract
• You can re-host assets within 24 hours

• You prefer duration-first budgeting and a stable cloud ecosystem workflow

• Editing/restyling is central and you've confirmed stable access semantics

FAQ

Q: How do I switch between text-to-video and image-to-video on EvoLink?

Q: Webhook or polling—what's safer?

Q: Why must I re-host the result?

Links expire in 24 hours. Download and store outputs promptly.

Q: What's the right unit for unit economics?

Cost per successful output, not per attempt. Track attempts-per-success, retries, and policy failure rate.

Q: How do I avoid duplicate tasks when users retry?

Start Building with Seedance 1.5 Pro Today

You've seen the contract. You understand the tradeoffs. Now turn it into a production feature.

• One API key for Seedance 1.5 Pro, Veo 3.1, Kling, and other models
• Async tasks + callbacks with defined retry semantics
• Usage-based billing with transparent credits and no minimums

Most teams integrate in under an hour.