How to Use Seedance 2.5 API on LinkModel

TL;DR: The Seedance 2.5 API uses LinkModel's asynchronous video workflow: submit a request to POST /v1/videos/generations, save the returned task_id, poll GET /v1/videos/generations/{task_id}, and read file_url after the task reaches Success. On LinkModel, the model preset is seedance-2-5. Do not substitute Volcano Engine's platform-specific ID, doubao-seedance-2-5-260628, or the dotted spelling seedance-2.5.

Availability checked August 20, 2026: Seedance 2.5 is available on LinkModel under the seedance-2-5 preset. Use the live model page to confirm the task types, request fields, and pricing exposed to your account before sending a production request.

This guide deliberately separates two contracts. ByteDance and Volcano Engine document what the upstream model can do. LinkModel's live model page and API schema determine which of those controls are exposed through the LinkModel endpoint.

What do you need before using Seedance 2.5 API?

You need three things:

1. A LinkModel account and API key created in the dashboard.
2. The exact model preset seedance-2-5 selected from the live model catalog.
3. curl for the first request, or Python 3 with the requests package for the complete polling example.

Store the key in an environment variable rather than source code:

export LINKMODEL_API_KEY="<YOUR_API_KEY>"

Before creating a production task, open the Seedance 2.5 model page and confirm the task type you need, current pricing, and the model-specific schema. Availability and optional request fields can change independently, so copy the current preset and supported parameters instead of relying on an older integration.

Which Seedance 2.5 model ID should you use?

Use seedance-2-5 in LinkModel requests. Model identifiers belong to the platform that accepts the request, so similar names are not interchangeable.

Do not use seedance-2.5 in a LinkModel request. The hyphenated preset is also the identifier used by the LinkModel release-status article.

How do you submit a Seedance 2.5 video request?

LinkModel generation APIs use a create-then-query lifecycle. The smallest useful text-to-video request contains the model and prompt:

curl --fail-with-body --request POST \
  --url https://api.linkmodel.ai/v1/videos/generations \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance-2-5",
    "prompt": "A continuous 20-second product film. 0-5s: a sealed glass bottle on black stone. 5-14s: the camera orbits as condensation forms. 14-20s: a slow push-in, synchronized room tone and one clean final frame."
  }'

A successful create response uses LinkModel's standard envelope and returns a task_id inside data. Save both task_id and request_id: the first identifies the generation, while the second is useful when debugging a failed API call.

Use that identifier with the matching query endpoint:

curl --fail-with-body --request GET \
  --url "https://api.linkmodel.ai/v1/videos/generations/<TASK_ID>" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY"

Do not add duration, resolution, reference-media, editing, or extension fields by copying them from another provider. Use only the exact names, types, enums, and combinations shown by the current LinkModel Seedance 2.5 schema.

How do you poll the task and retrieve the video?

The following Python example submits a task, waits before the first poll, handles every documented terminal state, applies a timeout, and returns the final file_url.

import os
import time
import requests

BASE_URL = "https://api.linkmodel.ai/v1/videos/generations"
API_KEY = os.environ["LINKMODEL_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
TERMINAL = {"success", "failed", "cancelled"}


def check_envelope(payload):
    if payload.get("code") != 0:
        message = payload.get("msg") or payload.get("message") or "API request failed"
        request_id = payload.get("request_id", "unknown")
        raise RuntimeError(f"{message} (request_id={request_id})")
    return payload["data"]


def generate_video(prompt, timeout_seconds=900):
    create_response = requests.post(
        BASE_URL,
        headers=HEADERS,
        json={"model": "seedance-2-5", "prompt": prompt},
        timeout=30,
    )
    create_response.raise_for_status()
    task_id = check_envelope(create_response.json())["task_id"]

    deadline = time.monotonic() + timeout_seconds
    time.sleep(30)

    while time.monotonic() < deadline:
        query_response = requests.get(
            f"{BASE_URL}/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        query_response.raise_for_status()
        task = check_envelope(query_response.json())
        status = str(task.get("status", "")).lower()

        if status not in TERMINAL:
            time.sleep(8)
            continue
        if status == "success":
            file_url = task.get("file_url")
            if not file_url:
                raise RuntimeError(f"Task {task_id} succeeded without file_url")
            return task_id, file_url

        reason = task.get("error") or task.get("message") or status
        raise RuntimeError(f"Task {task_id} ended as {status}: {reason}")

    raise TimeoutError(f"Task {task_id} exceeded {timeout_seconds} seconds")


task_id, file_url = generate_video(
    "A quiet railway platform at blue hour, one continuous tracking shot, "
    "natural station ambience, restrained documentary color."
)
print({"task_id": task_id, "file_url": file_url})

LinkModel's current task documentation recommends waiting about 30 seconds before polling a video, then slowing the interval as the job ages. Stop on Success, Failed, or Cancelled; never poll once per second in a tight loop. Download the result to storage you control instead of treating a generated URL as permanent storage.

Which Seedance 2.5 capabilities are officially verified?

The upstream Seedance 2.5 model page and Volcano Engine tutorial support the following model-level facts. They do not prove that every field is available through LinkModel on launch day.

The “50 references” headline therefore means a typed maximum of 30 images + 10 videos + 10 audio clips, not 50 arbitrary files. The Volcano endpoint also has special rules for editing, extension, aspect ratio, and adaptive duration. Treat those as upstream facts until the LinkModel schema explicitly exposes equivalent controls.

Volcano Engine account limits, task-record retention, and generated-URL lifetime are also vendor-specific. They must not be presented as LinkModel limits or storage policy.

Can you use Seedance 2.5 for image-to-video and editing?

ByteDance documents image-guided generation, first/last-frame workflows, multimodal references, editing, and extension. LinkModel support is narrower: a workflow is available only when the live model page lists that task type and the LinkModel parameter schema defines its fields.

This distinction prevents a common integration failure. An image_url field accepted by one model or provider may be named differently, require an array, or be unavailable on another endpoint. Copy the launch-day LinkModel schema exactly instead of guessing from the Seedance 2.0 guide or Volcano Engine request body.

Add image-to-video from the current 2.5 schema in this order:

1. Confirm image-to-video appears on the model page.
2. Check supported URL formats, file sizes, dimensions, and reference counts.
3. Send one minimal image request before combining multiple references.
4. Verify that the output, cost, and task log match the requested configuration.
5. Add editing or extension only if those task modes are explicitly exposed.

How do you migrate from Seedance 2.0 to Seedance 2.5?

Keep the asynchronous task client, but do not assume migration is only a string replacement. Use this checklist:

1. Preserve the POST /v1/videos/generations and GET /v1/videos/generations/{task_id} lifecycle.
2. Change the preset from seedance-2-0 to seedance-2-5 in a canary environment.
3. Compare the two model schemas field by field and remove unsupported 2.0 options.
4. Treat resolution as a platform-specific field. Volcano Engine now documents 480p, 720p, and 1080p for 2.5, while the current LinkModel public pricing table lists 480P and 720P; neither source documents 4K for 2.5.
5. Re-run text-to-video and image-to-video fixtures with safe, owned reference media.
6. Measure successful-output cost, latency, failure behavior, and output retrieval before routing production traffic.

The existing Seedance 2.0 API guide remains useful for understanding the LinkModel task pattern. Use it as workflow context, not as the 2.5 parameter contract.

For the migration decision itself, compare the official trade-offs in Seedance 2.5 vs 2.0. Once the endpoint works, use the Seedance 2.5 prompt guide to turn a 30-second brief into timed story beats and explicit reference roles.

How do you troubleshoot Seedance 2.5 API errors?

Do not retry every failure blindly. Authentication and validation errors need a configuration fix; only transient creation or processing failures should enter a bounded retry policy with backoff.