Seedance 2.5 Video Generation | API Docs

Create an asynchronous Seedance 2.5 job. For Seedance 2.0, use its separate parameter reference.

Authentication

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

modelstringrequired

seedance-2.5.

promptstring

Video prompt. Required for text-only generation; may be omitted or blank when image/video references are supplied. Omit it for draft_task reuse. metadata.content text items are discarded; top-level prompt is authoritative.

durationnumberDefault: 5

Integer from 4 through 30, or -1 for automatic duration. Native seconds accepts the equivalent integer string. metadata.duration is also accepted. Supplied duration aliases must agree. Omit all duration controls for draft_task reuse.

resolutionstringDefault: 720p

480p, 720p, or 1080p. Native size may specify resolution; metadata.resolution has precedence. 4k is not supported.

aspectRatiostringDefault: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive. aspect_ratio, ratio, and metadata.ratio are accepted. Existing ratio values in size remain accepted for compatibility, but a resolution value in size means resolution. First/last-frame input requires adaptive; it is selected when frame roles are present without an explicit ratio.

metadataobject

Accepts resolution, ratio, duration, content, generate_audio, and output_format. Set generate_audio to a boolean for generated audio. Top-level generateAudio / generate_audio are aliases; use only one audio control.

imageUrlsstring[]

Reference images. images, imageUrl, image_urls, and image_url are aliases. Native images shorthand uses its first two images as first/last frames; imageUrls retains reference-image semantics.

imageWithRolesobject[]

Role-based images with url and role: first_frame, last_frame, or reference_image. image_with_roles is an alias. Typed metadata.content is also accepted.

videoUrlsstring[]

Reference videos. videoUrl, video_urls, and video_url are aliases.

audioUrlsstring[]

Reference audio. audioUrl, audio_urls, and audio_url are aliases. Requires an image or video in the same request.

outputFormatstringDefault: mp4

mp4 only. output_format and metadata.output_format are accepted. mov and watermark are not supported.

callback_urlstring

Optional native callback URL. Availability depends on the selected channel; use GET https://api.requestbeam.com/v1/jobs/{jobId} as the authoritative result.

Multimodal Content

Media URLs may use public HTTP(S) URLs or existing asset:// identifiers.

Type	Nested field	Roles
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`
`draft_task`	`draft_task.id`	No role; sample reuse only

Up to 30 images, 10 videos, and 10 audio files, with at most 50 media items total, are accepted across shorthand and typed content. Audio requires an image or video. Use top-level prompt instead of type: "text" content. Supply only one alias for each setting. Unsupported controls are rejected. Top-level first_frame_url, last_frame_url, reference_image_urls, reference_video_urls, and reference_audio_urls are role-specific shorthand. Unlisted fields inside content items are not forwarded.

Draft-Task Reuse

draft_task is exclusive to Seedance 2.5. It reuses an existing compatible completed sample; this page does not define sample-creation controls.

metadata.content must contain exactly one draft_task item.
Prefer the existing sample's Synapse decimal-string jobId as draft_task.id.

An existing recorded platform task_... identifier is also accepted; do not use an upstream raw task ID or invent an identifier.

The sample must belong to the same account, use the same model and processing

channel, be completed, and have been created less than 7 days ago.

Do not supply prompt, image/video/audio inputs, duration, ratio, seed,

generate_audio, output format, or omni_reference_task_type. The sample's settings are reused.

Output resolution may be supplied.

The compatibility and ownership checks may reject reuse even when the referenced task completed successfully. Do not assume every normal generation is a reusable sample.

Request Examples

Multimodal Reference

json

{
  "model": "seedance-2.5",
  "prompt": "Keep the referenced character and camera movement in a coherent film",
  "seconds": "8",
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/camera.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
    ]
  }
}

First and Last Frames

json

{
  "model": "seedance-2.5",
  "duration": 5,
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
    ]
  }
}

Reuse an Existing Sample

Replace EXISTING_SAMPLE_JOB_ID with the actual compatible completed sample's returned jobId. The placeholder below is not a working task identifier.

json

{
  "model": "seedance-2.5",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {"type": "draft_task", "draft_task": {"id": "EXISTING_SAMPLE_JOB_ID"}}
    ]
  }
}

Submission and Result

Response data contains jobId, status, model, and message. Submission success means the job was accepted, not completed. Poll GET https://api.requestbeam.com/v1/jobs/{jobId} with the same account's API Key. See Get Async Job.

When status is COMPLETED, read data.outputResult. Accept both string and array values for each result object's url.