Seedance 2.5 · Text with Reference

Learn how to use Seedance 2.5 · Text with Reference.

Developer API pricing

Provider: SeeAPI

USD estimate: $0.0037 / credit · Estimated equivalent, not an additional charge.

480p: 34 credits/sec (≈ $0.13/sec, no video) | 20 credits/sec (≈ $0.075/sec, with video)

720p: 74 credits/sec (≈ $0.28/sec, no video) | 45 credits/sec (≈ $0.17/sec, with video)

1080p: 185 credits/sec (≈ $0.69/sec, no video) | 110 credits/sec (≈ $0.41/sec, with video)

Note: No video = unit price × output duration; with video = unit price × (output + reference video duration).

Query Task Status

After submitting a task, use the unified query endpoint to check progress and retrieve results:

Get Task DetailsLearn how to query task status and retrieve generation results

Related Resources

Market Overview

Explore all available models

Credits & Billing

View credit balance, plans, and billing activity

Usage

Review API usage and credit consumption

Callbacks

Manage the secret used to verify generation webhook signatures. Callback URLs are supplied when you create each generation.

Webhook flow

Callback URL per generation.

Webhook signing key

Request

POST/v1/generations

AuthorizationSend your API key in the Authorization header using the Bearer scheme.Authorization: Bearer ****************

Header Params

stringrequired

A unique key for this generation request. Reuse the same value only when retrying the identical request body.

max length: 255

Example:: order-20260818-001

Body Params

application/json

stringrequired

The public model ID documented on this page. Use seedance-2-5 for this Endpoint.

Allowed:seedance-2-5

Default:: seedance-2-5
Example:: seedance-2-5

stringrequired

The public Endpoint ID for the selected model. Use the Endpoint whose input schema matches this request.

Allowed:reference-to-video

Default:: reference-to-video
Example:: reference-to-video

stringoptional

Optional public Provider ID. Omit this field to use the Endpoint's default Provider.

Allowed:seeapibyteplus

Default:: seeapi
Example:: seeapi

objectrequired

Provider-specific input object. Its accepted fields and validation rules depend on the selected provider.

Provider parameters

SeeAPIseeapiDefault Provider

stringoptional

Describe how the supplied reference assets should be used to generate, edit, or extend the video.

Recommended prompt length: no more than 500 Chinese characters or 1,000 English words.

max length: 30000

array <uri>optional

Provide image references for subject identity, composition, style, or visual consistency.

At least one of reference_images, reference_video, or reference_audio is required.
Accepted formats: JPEG, PNG, WebP, BMP, TIFF, and GIF.
Each image must be smaller than 30 MB.
Each image must be 300–6,000 pixels on each side, with an aspect ratio of 0.4–2.5.
Upload up to 30 reference images.
A request may contain at most 50 reference assets in total.

max items: 30

array <uri>optional

Provide video references for motion, structure, editing, or extension.

At least one of reference_images, reference_video, or reference_audio is required.
Accepted formats: MP4 and MOV.
Each video must be 480p or 720p, 2–30 seconds, and no larger than 200 MB.
Each video must be 300–6,000 pixels on each side, with an aspect ratio of 0.4–2.5.
Each video must contain 409,600–927,408 total pixels (width × height).
Frame rate must be 24–60 FPS.
Upload up to 10 videos.
The combined duration of reference videos must not exceed 30 seconds.

max items: 10

array <uri>optional

Provide audio references for timing, sound, or motion.

At least one of reference_images, reference_video, or reference_audio is required.
The combined duration of reference audio must not exceed 30 seconds.

max items: 10

stringoptional

Choose the output width-to-height ratio.

Video editing requires aspect_ratio=adaptive and duration_seconds=-1. Provide a reference_video; the output preserves the selected reference video’s aspect ratio and approximately matches its duration.
Using a video as a reference to generate a new video is different from editing the source video; ordinary reference-based generation supports the listed aspect ratios.

Allowed:16:94:31:13:49:1621:9adaptive

Default:: adaptive

numberoptional

Choose the output duration in seconds: 4–30, or the special value -1 for automatic duration selection.

Special value: -1. The model automatically selects a suitable output duration. For video editing, the output approximately matches the selected reference video’s duration; for other task types, it selects a duration within 4–30 seconds.
Video editing requires duration_seconds=-1 and aspect_ratio=adaptive. Provide a reference_video.

min: 4max: 30

Default:: 5

stringoptional

Select the requested output resolution. Higher resolutions may increase processing time and credit usage.

Allowed:480p720p1080p

Default:: 480p

booleanoptional

Whether the generated video should include an audio track when this Provider supports audio generation.

Default:: true

stringoptional

Select the output video container: mp4 or mov.

Allowed:mp4mov

Default:: mp4

booleanoptional

Return the generated video last frame when available.

Default:: false

booleanoptional

Enable NSFW checker.

Default:: true

BytePlusbyteplus

stringoptional

Describe how the reference assets should be used. BytePlus recommends no more than 500 Chinese characters or 1,000 English words.

array <uri>optional

Accepted formats: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF. Maximum file size: 30 MB per file.

Provide at least one reference image, reference video, or reference audio file.

max items: 30

array <uri>optional

Accepted formats: MP4 and MOV. Each video must be 2–30 seconds, no larger than 200 MB, 24–60 FPS, 300–6,000 pixels on each side, with an aspect ratio of 0.4–2.5 and 407,696–8,295,044 total pixels. Upload up to 10 videos; their combined duration must not exceed 30 seconds. Accepted formats: video/mp4, video/quicktime.

At least one of reference_images, reference_video, or reference_audio is required.
Accepted formats: MP4 and MOV.
Each video must be 2–30 seconds and no larger than 200 MB.
Each side must be 300–6,000 pixels, with an aspect ratio of 0.4–2.5.
Each video must contain 407,696–8,295,044 total pixels (width × height).
Frame rate must be 24–60 FPS.
Upload up to 10 videos.
The combined duration of reference videos must not exceed 30 seconds.

max items: 10

array <uri>optional

Accepted formats: audio/wav, audio/mpeg. Maximum file size: 15 MB per file.

max items: 10

stringoptional

Choose the output aspect ratio. adaptive follows the reference video’s aspect ratio for video editing and extension.

Video editing requires aspect_ratio=adaptive and duration_seconds=-1. Provide a reference_video; the output follows the selected video’s aspect ratio and approximately matches its duration.
Video extension requires aspect_ratio=adaptive to follow the selected reference video’s aspect ratio; it does not require duration_seconds=-1.
These restrictions also apply when omni_reference_task_type=auto and the model identifies an editing or extension task from the prompt.
Using a reference video to generate a new video (omni_reference_task_type=reference) does not impose these edit-mode restrictions; other supported aspect ratios remain available.

Allowed:16:94:31:13:49:1621:9adaptive

Default:: adaptive

numberoptional

Choose the output duration in seconds: 4–30, or the special value -1 for automatic duration selection.

Special value: -1. For a video editing task, the output approximately matches the selected reference video’s duration. For other task types, the model automatically selects an integer duration from 4 to 30 seconds.
Video editing requires duration_seconds=-1 and aspect_ratio=adaptive. Provide a reference_video.
Video extension requires aspect_ratio=adaptive, but does not require duration_seconds=-1.

Allowed:-1456789101112131415161718192021222324252627282930min: -1max: 30

Default:: 5

stringoptional

Allowed:480p720p1080p

Default:: 480p

booleanoptional

Default:: true

stringoptional

Choose MP4 or MOV output.

Allowed:mp4mov

Default:: mp4

numberoptional

Use -1 for a random seed, or provide a fixed integer for reproducibility.

min: -1

Default:: -1

booleanoptional

Return the generated video's last frame when available.

Default:: false

stringoptional

Choose how BytePlus handles the reference assets. auto: Let the model determine the task type from the prompt. reference: Generate a new video from the supplied references. edit: Edit a reference video; aspect_ratio must be adaptive and duration_seconds must be -1. extend: Extend a reference video; aspect_ratio must be adaptive.

Allowed:autoreferenceeditextend

Default:: auto

string <uri>optional

Optional absolute HTTPS URL that receives terminal generation updates. If omitted, query the task-details endpoint with the returned generation ID.

max length: 2048

Example:: https://client.example.com/webhooks/seeapi

Responses

202Generation accepted and processing

Bodyapplication/json

objectrequired

stringrequired

Example:: task_xxx

stringrequired

Example:: seedance-2-5

stringrequired

Example:: reference-to-video

stringrequired

Allowed:seeapibyteplus

seeapi: SeeAPI
byteplus: BytePlus

Example:: seeapi

stringrequired

Allowed:processing

Example:: processing

numberrequired

Estimated public credits. Values can include up to three decimal places.

Example:: 170

numberrequired

Consumed public credits, with up to three decimal places.

Example:: 0

numberrequired

Refunded public credits, with up to three decimal places.

Example:: 0

string <date-time>required

Example:: 2026-08-18T10:00:00Z

string <date-time>required

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this response is an idempotent replay of an earlier request.

Example:: false

200Idempotent replay of an existing generation request

Bodyapplication/json

objectrequired

stringrequired

Example:: task_xxx

stringrequired

Example:: seedance-2-5

stringrequired

Example:: reference-to-video

stringrequired

Allowed:seeapibyteplus

seeapi: SeeAPI
byteplus: BytePlus

Example:: seeapi

stringrequired

Allowed:processing

Example:: processing

numberrequired

Estimated public credits. Values can include up to three decimal places.

Example:: 170

numberrequired

Consumed public credits, with up to three decimal places.

Example:: 0

numberrequired

Refunded public credits, with up to three decimal places.

Example:: 0

string <date-time>required

Example:: 2026-08-18T10:00:00Z

string <date-time>required

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this response is an idempotent replay of an earlier request.

Example:: false

400

Invalid JSON, parameters, Schema, or API Policy

401

Invalid API Key or authentication failed

402

Insufficient credits

403

The current request is not allowed

404

Model, Endpoint, or task not found

409

Idempotency conflict or the same request is still being created

413

Request body is too large

429

Too many requests

503

Service temporarily unavailable

Code Examples

Request

const response = await fetch("https://api.seeapi.com/v1/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": "order-20260818-001",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "seedance-2-5",
  "endpoint": "reference-to-video",
  "provider": "seeapi",
  "input": {
    "aspect_ratio": "adaptive",
    "duration_seconds": 5,
    "resolution": "480p",
    "generate_audio": true,
    "output_format": "mp4",
    "return_last_frame": false,
    "nsfw_checker": true
  },
  "callback_url": "https://client.example.com/webhooks/seeapi"
})
});

const result = await response.json();

ResponseHTTP 202

{
  "generation": {
    "id": "task_xxx",
    "model": "seedance-2-5",
    "endpoint": "reference-to-video",
    "provider": "seeapi",
    "status": "processing",
    "estimated_credits": 170,
    "consumed_credits": 0,
    "refunded_credits": 0,
    "created_at": "2026-08-18T10:00:00Z",
    "updated_at": "2026-08-18T10:00:00Z"
  },
  "idempotent": false
}

const response = await fetch("https://api.seeapi.com/v1/generations", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "order-20260818-001", "Content-Type": "application/json" }, body: JSON.stringify({ "model": "seedance-2-5", "endpoint": "reference-to-video", "provider": "seeapi", "input": { "aspect_ratio": "adaptive", "duration_seconds": 5, "resolution": "480p", "generate_audio": true, "output_format": "mp4", "return_last_frame": false, "nsfw_checker": true }, "callback_url": "https://client.example.com/webhooks/seeapi" }) }); const result = await response.json();

{ "generation": { "id": "task_xxx", "model": "seedance-2-5", "endpoint": "reference-to-video", "provider": "seeapi", "status": "processing", "estimated_credits": 170, "consumed_credits": 0, "refunded_credits": 0, "created_at": "2026-08-18T10:00:00Z", "updated_at": "2026-08-18T10:00:00Z" }, "idempotent": false }

Responses

202Generation accepted and processing

Bodyapplication/json

objectrequired

stringrequired

Example:: task_xxx

stringrequired

Example:: seedance-2-5

stringrequired

Example:: reference-to-video

stringrequired

Allowed:seeapibyteplus

seeapi: SeeAPI
byteplus: BytePlus

Example:: seeapi

stringrequired

Allowed:processing

Example:: processing

numberrequired

Estimated public credits. Values can include up to three decimal places.

Example:: 170

numberrequired

Consumed public credits, with up to three decimal places.

Example:: 0

numberrequired

Refunded public credits, with up to three decimal places.

Example:: 0

string <date-time>required

Example:: 2026-08-18T10:00:00Z

string <date-time>required

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this response is an idempotent replay of an earlier request.

Example:: false

200Idempotent replay of an existing generation request

Bodyapplication/json

objectrequired

stringrequired

Example:: task_xxx

stringrequired

Example:: seedance-2-5

stringrequired

Example:: reference-to-video

stringrequired

Allowed:seeapibyteplus

seeapi: SeeAPI
byteplus: BytePlus

Example:: seeapi

stringrequired

Allowed:processing

Example:: processing

numberrequired

Estimated public credits. Values can include up to three decimal places.

Example:: 170

numberrequired

Consumed public credits, with up to three decimal places.

Example:: 0

numberrequired

Refunded public credits, with up to three decimal places.

Example:: 0

string <date-time>required

Example:: 2026-08-18T10:00:00Z

string <date-time>required

Example:: 2026-08-18T10:00:00Z

booleanrequired

Whether this response is an idempotent replay of an earlier request.

Example:: false

400

Invalid JSON, parameters, Schema, or API Policy

401

Invalid API Key or authentication failed

402

Insufficient credits

403

The current request is not allowed

404

Model, Endpoint, or task not found

409

Idempotency conflict or the same request is still being created

413

Request body is too large

429

Too many requests

503

Service temporarily unavailable