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 /video-generation, save the returned task_id, poll GET /query/video-generation, 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.

Publication gate, checked August 13, 2026: the LinkModel model detail route is reserved, but the public catalog and LinkModel API documentation does not yet list seedance-2-5. This guide is a launch-ready draft. Publish and run the examples only after the preset and its model-specific parameter schema appear in both places.

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 visible in 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 that it shows an active API action, the task type you need, current pricing, and the model-specific schema. A route returning HTTP 200 is not enough: the preset must appear in the catalog data.

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/api/v1/video-generation \
  --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/api/v1/query/video-generation?task_id=<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. Add optional fields only after the LinkModel Seedance 2.5 schema publishes their exact names, types, enums, and combinations.

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/api/v1"
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(
        f"{BASE_URL}/video-generation",
        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}/query/video-generation",
            headers=HEADERS,
            params={"task_id": task_id},
            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.

When the 2.5 schema is public, add image-to-video 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 /video-generation and GET /query/video-generation 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. Do not carry a 1080p or 4K assumption into 2.5; the verified upstream 2.5 endpoint currently exposes 480p and 720p.
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.

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.

Frequently asked questions about Seedance 2.5 API

Is Seedance 2.5 available through LinkModel?

The model detail route is reserved, but the public LinkModel catalog and documentation did not list the preset during the August 13, 2026 check. Publish this guide only after seedance-2-5 appears in the live catalog and its parameter schema is available.

Which Seedance 2.5 model ID should I use on LinkModel?

Use seedance-2-5. Volcano Engine uses doubao-seedance-2-5-260628 for its platform, and the identifiers are not interchangeable.

Does the Seedance 2.5 API support 4K?

No. The current Volcano Engine documentation lists 480p and 720p and explicitly says the endpoint does not support 1080p or 4K. Confirm the LinkModel schema at launch rather than inheriting a resolution from Seedance 2.0 or another provider.

How long can a Seedance 2.5 video be?

The official upstream documentation supports 4–30-second output and adaptive duration where the task permits. Editing has additional constraints, so use the duration options exposed by the live LinkModel schema.

Can I reuse my Seedance 2.0 integration?

You can reuse the LinkModel authentication, asynchronous task submission, polling, terminal-state handling, and output retrieval pattern. Compare the 2.0 and 2.5 parameter schemas before switching production traffic because optional fields and supported modes can differ.

What should you verify before publishing?

Run one authenticated request only after the model is live. Confirm the model preset, optional parameter schema, billing row, create response, polling states, final file_url, model-page CTA, and documentation URL. Then remove the publication-gate notice and update the availability FAQ with the verified launch status.

Sources checked August 13, 2026: LinkModel first API call, LinkModel tasks and polling, ByteDance Seedance 2.5, and the Volcano Engine Seedance 2.5 tutorial.