How to Use Seedance 2.5 Through an API

Seedance 2.5 is ByteDance's flagship video model. It generates native audio alongside the picture, runs up to 30 seconds in a single pass, and takes reference sets large enough to hold a character, a product, or a look across a whole scene. Reaching it programmatically usually means signing up with a model host, learning its polling conventions, and then building everything downstream yourself.

The Rendley API exposes Seedance 2.5 as one model id behind a single endpoint, POST /v1/ai/generate-video, next to every other video model. The same key that generates the clip also uploads your source media, runs transcription and translation, holds the timeline, and renders the finished MP4. The generation becomes one step in a pipeline rather than a product on its own.

This guide walks the whole path, from key and project through request, polling, and download, then the reference, editing, and extension flows, the cost model, and the failure modes that come up most often.

Before you start

You need three things before the first call.

The first is an API key. Create one in Rendley under Settings, then API Keys, and send it as a bearer token on every request.

The second is a workspace id, since projects live inside a workspace.

curl https://api.rendley.com/v1/workspaces \
  -H "Authorization: Bearer $RENDLEY_API_KEY"

The third is a project id. Every AI generation is scoped to a project, because the generated file lands in that project's media library where the rest of the API can reach it.

curl -X POST https://api.rendley.com/v1/projects \
  -H "Authorization: Bearer $RENDLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Seedance experiments", "workspace_id": "wsp_abc..." }'

The response carries the new project's id. Reuse one project for a batch of related generations, or create one per job if you prefer clean separation.

The request shape

Every AI generation endpoint on Rendley takes the same three fields.

{
  "project_id": "prj_123...",
  "model_id": "seedance-2.5",
  "params": { "prompt": "..." }
}

project_id is required. model_id selects the model and defaults to kling-v2.6 for video when you leave it out, so for Seedance you always pass it explicitly. Everything model-specific goes inside params. A duration or resolution sitting at the top level next to project_id is ignored silently, which is the single most common integration mistake.

GET /v1/ai/tools returns the live schema for every model, so you can check the current shape of params rather than trusting a blog post. Look for "id": "seedance-2.5" under generate_video.

Seedance 2.5 parameters

Three constraints are enforced at request time and will reject the whole call, so they are worth getting right up front.

• image and the reference_* family are mutually exclusive. Pick the first-frame flow or the reference flow, never both.
• last_frame_image requires both a start image and aspect_ratio: "adaptive".
• reference_audios needs at least one reference_images or reference_videos entry to attach to.

Every media field accepts either a public https:// URL or the file_hash of an upload that already lives in the same project. Mixing the two inside one array is fine.

Your first generation

Start the job. It returns immediately with a job id.

curl -X POST https://api.rendley.com/v1/ai/generate-video \
  -H "Authorization: Bearer $RENDLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_123...",
    "model_id": "seedance-2.5",
    "params": {
      "prompt": "Realistic nature documentary style, natural lighting. A chubby panda cub rolls down a grassy forest slope on a warm afternoon, fur catching the light. Handheld camera follows at low angle. Ambient forest sound, no music.",
      "duration": 8,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

Responses share one envelope, with data on success and error on failure. For the AI endpoints, data is the job id itself.

{ "data": "job_8f2c..." }

Poll the job

Video generation never returns fast enough to hold a connection open. Take the job id and poll GET /v1/jobs/{id} on an interval until the status is terminal, meaning completed, failed, or canceled. On success the output is in result_data, and on failure the reason is in error.

Poll every few seconds and expect to wait. Seedance 2.5 is slower than Kling or Veo, and a 30-second generation with a full reference set is minutes of work, not seconds. There is no benefit to polling faster than once per second, and no penalty for backing off to 10.

One detail catches people. input_data and result_data on the job are JSON encoded as strings, not nested objects, so parse them before reading fields.

Get the file

Export jobs hand back a direct storage_url. AI generation jobs do not. They return a media_id and a file_hash instead.

{ "media_id": "med_abc123", "file_hash": "sha256_def456..." }

Trade the hash for a presigned download URL.

curl "https://api.rendley.com/v1/uploads?project_id=prj_123...&hash=sha256_def456..." \
  -H "Authorization: Bearer $RENDLEY_API_KEY"

The storage_url in the response is time limited, so fetch the file promptly rather than storing the link.

That is the whole integration. Create, poll, download. Everything below covers the flows that make Seedance 2.5 worth choosing over a cheaper, faster model.

Reference images for character consistency

The reason to reach for Seedance 2.5 over Kling or Veo is usually consistency across shots. Give it up to 30 reference images and it will carry a character, a product, or a look through the whole generation.

{
  "project_id": "prj_123...",
  "model_id": "seedance-2.5",
  "params": {
    "prompt": "At the dusk launch site in @Image 1, the guardian robot from @Image 2 supports the elderly grandmother from @Image 3 as they walk through the grass. Handheld medium shot, warm sunset against cool twilight, realistic live-action texture. Wind and distant launch-site ambience, no music.",
    "reference_images": [
      "https://rendley.com/seedance/storyboard-film-ref-2.jpg",
      "https://rendley.com/seedance/storyboard-film-ref-4.jpg",
      "https://rendley.com/seedance/storyboard-film-ref-3.jpg"
    ],
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

The @Image N numbering follows the order of the array. Give every reference exactly one job in the prompt, whether a face, an environment, or a product. A reference with no stated job gets blended in unpredictably, and a reference the prompt never mentions still influences the output.

Reference images stay on the cheaper pricing tier. Reference videos do not, which is important enough to have its own section below.

First and last frame

Generate an opening frame with an image model, generate a closing frame, and let Seedance interpolate between them. This is the most controllable flow available, and it chains naturally on Rendley because POST /v1/ai/generate-image drops its output into the same project.

{
  "project_id": "prj_123...",
  "model_id": "seedance-2.5",
  "params": {
    "prompt": "The camera pushes in slowly as the sun clears the ridge and the fog burns off the valley floor.",
    "image": "sha256_openingframe...",
    "last_frame_image": "sha256_closingframe...",
    "aspect_ratio": "adaptive",
    "duration": 6
  }
}

Both frames must share an aspect ratio, and aspect_ratio must be adaptive, which tells the model to take its output shape from the first image rather than a fixed preset. Both fields here are file hashes rather than URLs, because these images were generated into the project a moment earlier.

Editing and extension

Pass a reference_videos entry with an edit instruction and Seedance 2.5 rewrites part of a clip instead of generating a new one. Both editing and extension require aspect_ratio: "adaptive" and duration: -1; these modes infer their timing from the source video and the instruction rather than a fixed output-length parameter.

Editing replaces, removes, or modifies something inside the clip.

{
  "params": {
    "prompt": "Edit @Video 1. Replace the setting with the medieval stone arena in @Image 1. Replace the fighter in dark clothing with @Image 2 and the fighter in light clothing with @Image 3. Keep the original actions, camera move, and rhythm unchanged.",
    "reference_videos": ["https://rendley.com/seedance/duel-in.mp4"],
    "reference_images": [
      "https://rendley.com/seedance/duel-ref-1.jpg",
      "https://rendley.com/seedance/duel-ref-2.jpg",
      "https://rendley.com/seedance/duel-ref-3.jpg"
    ],
    "aspect_ratio": "adaptive",
    "duration": -1
  }
}

Extension continues past the last frame.

{
  "params": {
    "prompt": "Extend the clip by 5 seconds. The bee takes off, and the camera follows it to a second flower where pollen shakes loose in slow motion.",
    "reference_videos": ["https://rendley.com/seedance/bee-in.mp4"],
    "aspect_ratio": "adaptive",
    "duration": -1
  }
}

For extension, state the desired continuation length in the prompt. Keep the API parameter at -1 so Seedance can follow the extension flow.

Reference videos are capped at 10 files and 30 seconds in total.

Lip sync with reference audio

Attach up to 10 reference audio files and Seedance drives mouth movement from them. The one constraint to remember is that reference_audios cannot stand alone. It needs at least one reference image or reference video to attach the voice to.

{
  "params": {
    "prompt": "The presenter from @Image 1 speaks directly to camera in the same studio, gesturing naturally. Match lip movement to @Audio 1 while keeping the character and setting consistent.",
    "reference_images": ["https://rendley.com/seedance/dubbing-in.jpg"],
    "reference_audios": ["https://rendley.com/seedance/dubbing-reference-audio.mp3"],
    "duration": 30,
    "aspect_ratio": "16:9"
  }
}

If the voiceover is not recorded yet, generate it first with POST /v1/ai/text-to-speech in the same project and pass the resulting file hash straight into reference_audios.

What it costs

Every billable endpoint has a matching /cost twin that prices the exact request without running it. Send the identical body.

curl -X POST https://api.rendley.com/v1/ai/generate-video/cost \
  -H "Authorization: Bearer $RENDLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_123...",
    "model_id": "seedance-2.5",
    "params": { "prompt": "...", "duration": 8, "resolution": "720p" }
  }'

Seedance 2.5 is priced per second of output, and the rate depends on resolution and on whether the request includes reference videos. One credit is one US cent.

The tier jump is the thing to plan around. Adding a single reference video makes a 720p request roughly four times more expensive per second, so a 30-second 720p edit is a large charge. Reference images and reference audios do not trigger it. Only reference_videos does.

Credits are locked when the job is enqueued. With duration: -1 the real length is not known yet, so Rendley's current cost calculation uses a five-second baseline. Call /cost immediately before any request where the price matters; if the balance is short, the endpoint returns 402 Payment Required before work starts.

These figures are current at the time of writing, and the /cost endpoint is the authority.

Failure modes

Most Seedance failures come from a small set of causes.

• A parameter placed at the top level instead of inside params is dropped silently, and you get a default 5-second clip with no obvious reason.
• Mixing image with reference_images combines two different flows, and the request is rejected.
• A last_frame_image without adaptive is rejected, because the last-frame flow inherits its shape from the first image and a fixed aspect ratio contradicts that.
• Editing with a fixed duration fails, because editing preserves the source length. Use -1.
• A reference the prompt never names still influences the output. Trim the array to what the prompt uses.
• A prompt over 2000 characters is rejected. Compress a long storyboard rather than letting the model truncate it.

When a job fails after being accepted, GET /v1/jobs/{id} still returns 200 with status: "failed" and a reason in error. Jobs do not retry themselves, so surface the reason and start a new one once the cause is fixed.

When to pick something else

Seedance 2.5 is not the default, for good reason. It caps at 720p and it is slow. For a standard 5 or 10 second clip that needs no references and no long duration, kling-v2.6 returns faster and cheaper, and veo-3.1 looks better at 1080p for hero shots.

Reach for Seedance 2.5 when the job needs its particular combination of long single-pass generation, large multimodal reference sets, synchronized audio, and targeted editing. The clearest reasons to prefer it over Seedance 2.0 are a clip longer than 15 seconds or more than nine reference images.

Next steps

The Rendley API docs cover the endpoints in full, including jobs and polling and rendering. For prompt craft rather than plumbing, read how to prompt Seedance 2.5, which walks through ByteDance's official examples in full. To feel the model before writing any code, generate from a prompt here.