API Documentation

Quick start

Create an API key in the console and export it as ONLYSEEDANCE_API_KEY. These three calls submit a task, check it and save the video.

curl https://api.onlyseedance.com/v1/videos/generations \
  -H "Authorization: Bearer $ONLYSEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A slow aerial shot over a foggy pine forest at sunrise"
  }'

curl https://api.onlyseedance.com/v1/videos/$REQUEST_ID \
  -H "Authorization: Bearer $ONLYSEEDANCE_API_KEY"

curl -L https://api.onlyseedance.com/v1/videos/$REQUEST_ID/content \
  -H "Authorization: Bearer $ONLYSEEDANCE_API_KEY" \
  -o output.mp4

import os
import time
import requests

BASE = "https://api.onlyseedance.com"
headers = {"Authorization": f"Bearer {os.environ['ONLYSEEDANCE_API_KEY']}"}

job = requests.post(
    f"{BASE}/v1/videos/generations",
    headers=headers,
    json={"model": "seedance-2.5", "prompt": "A slow aerial shot over a foggy pine forest at sunrise"},
    timeout=60,
)
job.raise_for_status()
request_id = job.json()["request_id"]

while True:
    task = requests.get(f"{BASE}/v1/videos/{request_id}", headers=headers, timeout=60).json()
    if task["status"] != "pending":
        break
    time.sleep(10)

if task["status"] == "done":
    video = requests.get(f"{BASE}/v1/videos/{request_id}/content", headers=headers, timeout=600)
    video.raise_for_status()
    with open("output.mp4", "wb") as f:
        f.write(video.content)
else:
    print(task.get("error"))

Authentication

Send your key as a Bearer token: Authorization: Bearer YOUR_API_KEY. Keys are created on the console's API Keys page, and every key of an account spends the same balance.

Call the API from your own servers. Never put a key in a web page or a mobile app, and delete any key you think has leaked: a new one takes seconds to create.

Endpoints

The base URL is https://api.onlyseedance.com. Requests and responses are JSON.

Status and download requests must use a key of the account that submitted the task.

Models

Pass one of these IDs as model. Prices per second for each resolution are on the pricing page.

Text to video

Only prompt is required. Fields you leave out default to 5 seconds at 720p in 16:9.

{
  "model": "seedance-2.5",
  "prompt": "A slow aerial shot over a foggy pine forest at sunrise",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

Each request renders one video.

Image, video and audio references

Send images, videos or audio for the model to follow: a subject's look, a motion, a beat. Name them in the prompt as @Image 1, @Video 1 or @Audio 1; assets you do not name are still used.

{
  "model": "seedance-2.5",
  "prompt": "The woman in @Image 1 dances to the beat of @Audio 1, moving like the dancer in @Video 1",
  "duration": 10,
  "resolution": "720p",
  "reference_images": [{"url": "https://example.com/woman.png"}],
  "reference_videos": [{"url": "https://example.com/dance.mp4"}],
  "reference_audios": [{"url": "https://example.com/beat.mp3"}]
}

Each entry is an object with an HTTPS url that downloads without signing in. Reference videos are billed by their length at the with-video rate on the pricing page; images and audio are free.

Photos and videos of real people work as references without any extra verification step. You must have the consent of every person who appears in them: see the Acceptable Use Policy.

First and last frames

start_image makes the video open on your image. Add end_image and the model fills in the motion between the two.

{
  "model": "seedance-2.5",
  "prompt": "Day turns into night over the same skyline as the lights come on",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive",
  "start_image": {"url": "https://example.com/day.png"},
  "end_image": {"url": "https://example.com/night.png"}
}

On Seedance 2.5, set aspect_ratio to adaptive: the video takes the ratio of the first frame. The 2.0 models also accept a fixed ratio, which crops the first frame to fit. Frames cannot be combined with reference assets in the same request.

Edit a video

Seedance 2.5 can rewrite footage you already have. The result keeps the source video's length and aspect ratio; you choose the resolution.

{
  "model": "seedance-2.5",
  "omni_reference_task_type": "edit",
  "prompt": "Make the colors warmer and keep everything else",
  "resolution": "720p",
  "reference_videos": [{"url": "https://example.com/street.mp4"}]
}

The first entry of reference_videos is the video to edit, 4–30 seconds long. Leave out duration and aspect_ratio. The source video's seconds are billed along with the output's, all at the with-video rate on the pricing page: editing a 5-second clip bills 10 seconds.

Task status

Check a task every 10–15 seconds. status is pending while the video renders, then done, failed or expired. Most tasks also report progress from 0 to 100.

{
  "request_id": "e9a36267-5a81-46ee-87a1-baf62bec7e9a",
  "status": "done",
  "model": "seedance-2.5",
  "progress": 100,
  "video": {
    "duration": 5,
    "url": "https://api.onlyseedance.com/v1/videos/e9a36267-5a81-46ee-87a1-baf62bec7e9a/content"
  }
}

A failed task carries an error object that says why, for example when the model's safety system refused the prompt or an input. Download finished videos within 24 hours; after that the task reports expired.

Billing

• You top up a USD balance in the console, from $5. There is no subscription and no expiry.
• Videos are billed per second of output at the price of their resolution. Reference videos add their seconds at the with-video rate.
• When you submit a task, its maximum price is held from your available balance. When the video is done, the actual price is charged and the rest is released.
• Failed and expired tasks are not charged: their hold is released in full.
• Every charge is listed with its request ID on the console's Usage page.

Errors

Every response carries an X-Client-Request-ID header. Include it when you contact us about a request.