Seedance 2.5 API Guide: Generate Video from Code or an AI Agent

Seedance 2.5 is a capable text- and reference-to-video model. Access today is pre-release and provider-mediated — it is not generally available, so treat everything below as expected behavior and verify with the provider before you ship. This is an independent guide; EvoLink is the recommended third-party provider (we are not affiliated with ByteDance). Request shapes follow EvoLink’s API — cross-check their docs before production.

Setup

Create an API key on EvoLink, add a balance, export the key, and you’re ready to test:

export EVOLINK_KEY="sk-..."

Billing has no public rates yet. It is expected to bill per second of output, native audio is included at no extra charge, and turning off content_filter is expected to cost about 1.1x. Verify the current model in the provider console before you build.

The generation request

The model id is seedance-2.5-reference-to-video (pre-release — keep it configurable so you can swap it when the provider finalizes it).

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer $EVOLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-reference-to-video",
    "prompt": "golden-hour drone pullback over a coastal city, anamorphic flare",
    "duration": 5,
    "quality": "720p",
    "generate_audio": true,
    "content_filter": true
  }'

Fields:

• model — pre-release id above; keep it configurable.
• prompt — text description of the shot.
• duration — seconds, expected range 4–30 (default 5). Verify the upper bound with the provider.
• quality — "480p" or "720p" (default "720p"). Higher resolutions such as 1080p are pending until provider docs confirm them — do not assume them.
• generate_audio — boolean, default true. Native audio is one pass at no extra charge.
• content_filter — boolean, default true. Setting false is expected to bill at ~1.1x.
• image_urls (≤30), video_urls (≤10), audio_urls (≤10) — reference files, see below.
• callback_url — optional webhook for completion.

The API responds with a task you then poll:

{ "id": "task_8f2c...", "status": "pending" }

Full parameter details live on our API page.

Polling for the result

Poll the task-detail endpoint until the status is completed:

curl "https://api.evolink.ai/v1/task-detail?id=task_8f2c..." \
  -H "Authorization: Bearer $EVOLINK_KEY"

status moves through pending → processing → completed (or failed). On completed, download the returned video URL.

A Node example

A minimal fetch-based flow — submit, then poll:

const KEY = process.env.EVOLINK_KEY;
const BASE = "https://api.evolink.ai/v1";
const MODEL = "seedance-2.5-reference-to-video"; // pre-release, keep configurable

async function generate() {
  const res = await fetch(`${BASE}/videos/generations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: MODEL,
      prompt: "the character walks through a market at dusk",
      duration: 5,
      quality: "720p",
      generate_audio: true,
      content_filter: true,
    }),
  });
  const { id } = await res.json();
  return id;
}

async function poll(id) {
  while (true) {
    const res = await fetch(`${BASE}/task-detail?id=${id}`, {
      headers: { "Authorization": `Bearer ${KEY}` },
    });
    const task = await res.json();
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error("generation failed");
    await new Promise((r) => setTimeout(r, 5000));
  }
}

const id = await generate();
const done = await poll(id);
console.log(done);

Reference files

You can attach reference media as URL lists, split by type:

• image_urls — up to 30 images.
• video_urls — up to 10 videos.
• audio_urls — up to 10 audio clips.

{
  "model": "seedance-2.5-reference-to-video",
  "prompt": "the character walks through the market, camera following the uploaded drone move",
  "image_urls": [
    "https://cdn.example.com/character_front.png",
    "https://cdn.example.com/character_profile.png"
  ],
  "video_urls": ["https://cdn.example.com/drone_move.mp4"],
  "audio_urls": ["https://cdn.example.com/score_draft.mp3"],
  "duration": 5,
  "quality": "720p",
  "generate_audio": true
}

Images pin identity and palette, video clips donate camera moves and motion style, audio drives tempo. For prompt patterns that exploit this, the prompt library shows real requests with outputs.

Cost control in production

No public rates are published yet, so treat these as directional and confirm in the provider console:

• Draft short, finish long. Billing is expected to be per second of output, so duration is the biggest cost lever. Iterate on short drafts before committing to the longer approved take.
• Cap duration server-side. Clamp duration in your own API layer so a bug can’t render long takes in a retry loop. Remember the expected range is 4–30 seconds.
• Mind content_filter. Leaving it on is the default; turning it off is expected to add ~10% to the bill.
• Audio is free. Native audio is included at no extra charge, so generate_audio: true doesn’t change the per-second math.

Recreate the current numbers from the pricing page once the provider publishes them, or eyeball any configuration in the playground.

Wiring it into an AI agent

Wrap the REST call as a single function tool in your agent framework (Claude Agent SDK, Vercel AI SDK, LangChain, or an MCP server). Expose parameters prompt, duration, quality, generate_audio, content_filter, and the reference URL lists — that mirrors the contract on the API page.

One production note: make the polling step a separate tool from the generation step. Agents handle “check if task X is done” much more gracefully than a single blocking call that holds a tool slot while the render runs. See the agent guide for the recommended shape.

Error handling worth building on day one

• Auth / balance errors — surface them to the user with a top-up link; don’t blindly retry.
• Rate limiting — back off exponentially; render times can stretch under load.
• failed status or content-policy rejections — log the returned reason; these are usually prompt issues, not transport bugs.

Because access is pre-release, also handle the case where the model id is not yet enabled for your account — keep it configurable and confirm provider support before you go to production.

Get a key, run the request above, and start testing: API quickstart →