how-tos

Seedance 2.5 API Guide: Call Seedance 2.5 Flash with cURL and Python

Poyo.ai Team
11 min read
Share:

A courier on a bicycle racing a clock tower at dawn, an editorial illustration for the Seedance 2.5 Flash API guide

The Seedance 2.5 Flash API is the faster, lower-cost tier of the Seedance 2.5 API, and on PoYo it is one model ID: seedance-2.5-flash. ByteDance released it on November 12, 2026; the Seedance 2.5 Flash model page has the playground and live prices. This guide takes you from a first cURL request to a production loop in Python, using the schema in the Seedance 2.5 Flash API docs as checked on November 16, 2026.

Seedance 2.5 Flash API at a glance

ItemValue
Submit endpointPOST https://api.poyo.ai/api/generate/submit
Status endpointGET https://api.poyo.ai/api/generate/status/{task_id}
Auth headerAuthorization: Bearer $POYO_API_KEY
Model IDseedance-2.5-flash (the page slug seedance-2-5-flash is not a model ID)
Required fieldsprompt, duration
DurationWhole seconds, 4–30
Resolution480p or 720p, default 720p
Aspect ratioauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, default auto
Audiogenerate_audio, default true
DeliveryAsync task: poll status or set callback_url

Your first Seedance 2.5 API request with cURL

Export your key as POYO_API_KEY and keep it on the server, never in browser code. This is a 5-second 480p text-to-video request, a low-cost first test at 92.5 credits:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash",
    "input": {
      "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

A successful submission returns code: 200 and a data object with task_id, status (always not_started right after submission), and created_time. It is a receipt, not a video. Save the task_id, then query it:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statuses move through not_started, running, finished, and failed. When the task is finished, the video URL is in data.files[].file_url with file_type: "video"; on failed, read data.error_message. Generated files stay accessible for 3 days, so copy them to your own storage.

Python: submit and poll with a hard deadline

The status docs recommend polling every 2–5 seconds, backing off on 429 and 5xx, and always setting a timeout. The loop below does all three and never resubmits on timeout, because a second submission is a second billable task.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    try:
        body = response.json()
    except ValueError:
        response.raise_for_status()
        raise
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(
            f"PoYo {body.get('code')} {err.get('type')}: "
            f"{err.get('message') or body.get('detail')}"
        )
    return body["data"]


task = checked(session.post(BASE + "/api/generate/submit", json={
    "model": "seedance-2.5-flash",
    "input": {
        "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)

deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
    r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(backoff)
        backoff = min(backoff * 2, 60)
        continue
    data = checked(r)
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Generation failed")
    if data["status"] == "finished":
        videos = [f["file_url"] for f in data.get("files", [])
                  if f.get("file_type") == "video"]
        print(videos[0], "credits:", data.get("credits_amount"))
        break
    backoff = 5
    time.sleep(5)
else:
    raise TimeoutError("Still running; poll the saved task ID later: " + task_id)

For reference, in PoYo testing on November 16, 2026, a 4-second 480p clip finished in about two minutes and a 30-second 720p clip in under three minutes, end to end. Times vary with load, so the 15-minute deadline is a safety bound, not an estimate.

Skip polling: use callback_url

Add a top-level callback_url next to model. When the task becomes finished or failed, PoYo sends a POST whose body is the task data object (task_id, status, files, created_time, error_message) without the code/data wrapper. Per the video webhook docs:

  • The URL must be public HTTPS, at most 2048 characters, with no private IPs.
  • Respond with a 2xx within 30 seconds; failed deliveries are retried up to 5 times with exponential backoff.
  • Verify X-Webhook-Signature as base64(HMAC-SHA256(task_id + "." + timestamp, key)), with timestamp from X-Webhook-Timestamp and the key from GET /api/api-keys/webhook-secret.
  • Make the handler idempotent. If every retry fails, the status endpoint still has the result.

The three input modes, with JSON bodies

The API picks the mode from the media you send. There is no mode field.

ModeSelected whenAspect ratio
Reference-to-videoAny of reference_image_urls, reference_video_urls, reference_audio_urls is non-emptyAny supported value
Image-to-video (first/last frame)image_urls is non-emptyauto or omit; output follows the first frame
Text-to-videoNo mediaAny supported value

image_urls and the reference fields go in separate requests. These bodies are the documented examples.

Text-to-video (30 seconds at 720p, with a timed shot list in the prompt):

{
  "model": "seedance-2.5-flash",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
    "duration": 30,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

First and last frame (one URL fixes the opening; a second fixes the ending):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}

Reference-to-video (refer to files by upload order as @Image1, @Video1, @Audio1):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
    "reference_image_urls": [
      "https://example.com/cat.png",
      "https://example.com/scarf.png",
      "https://example.com/bookstore.png"
    ],
    "reference_audio_urls": [
      "https://example.com/rhythm.mp3"
    ],
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

Validation rules to enforce before you submit

Checking these client-side saves a round trip and gives your users a clearer message than a generic 400.

FieldRule
promptRequired, non-empty string
durationRequired integer, 4–30
resolution480p or 720p only; 1080p needs seedance-2.5
aspect_ratioOne of the seven values; use auto or omit it with image_urls
image_urls1–2 URLs (first, then last frame); JPEG, PNG, or WebP, up to 30 MB each; not combined with reference fields
reference_image_urlsUp to 10; JPEG, PNG, or WebP, up to 30 MB each
reference_video_urlsUp to 5; MP4 or MOV, 2–30 s and up to 200 MB each; combined length at most 30 s
reference_audio_urlsUp to 5; MP3 or WAV, 2–30 s and up to 15 MB each; combined length at most 30 s; requires a reference image or video
All media URLsPublic HTTP or HTTPS, directly downloadable (no login pages or expiring previews)

The combined reference durations are checked when the task is submitted. The schema also sets additionalProperties: false on input, so do not send fields from other vendors' APIs such as seed or negative_prompt.

Errors worth handling

Always read the code field in the body: some validation errors from the submit endpoint come back with HTTP 200 and "code": 400. The error code reference lists these:

CodeTypeWhat to do
400validation_error, file_format_error, content_moderation_errorFix the request or media; do not retry unchanged
401authentication_errorCheck the Bearer header and that the key still exists
402insufficient_credits_errorTop up, then resubmit
429Rate limitBack off (1 s, 2 s, 4 s...) before polling or submitting again
500, 502, 503Server or upstreamRetry the status call with backoff; check status before resubmitting
Task failederror_message setLog the task ID; failed tasks report credits_amount: 0

How the first bill is calculated

Without reference videos, cost is output seconds times the per-second rate: 18.5 credits ($0.0925) at 480p, 41 credits ($0.205) at 720p, with 1 credit = $0.005. Generated audio adds nothing.

Request aboveBilled secondsCreditsUSD
cURL test, 5 s 480p592.5$0.4625
Text-to-video, 30 s 720p301,230$6.15
First/last frame, 5 s 720p5205$1.025
Reference images + audio, 6 s 480p6111$0.555

Adding any reference_video_urls switches to the lower with-video rate (11.5 credits at 480p, 25.5 at 720p) applied to billed seconds: output duration plus each reference video's length rounded down to whole seconds. The Seedance 2.5 API pricing breakdown works through those cases. The charge for a finished task appears as credits_amount in the status response.

Switch to Seedance 2.5 for 1080p

The request fields are the same, so moving a job from Flash to the standard Seedance 2.5 model is a model ID change:

{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}

Two details: the seedance-2.5 docs list resolution as required, so always send it, and the standard model allows up to 30 images, 10 videos, and 10 audio references. At 1080p it costs 114 credits ($0.57) per second. For the routing decision, see Seedance 2.5 Flash vs Seedance 2.5; for how Seedance 2.5 compares with another vendor, see Kling 4.0 vs Seedance 2.5.

Frequently asked questions

What is the model ID for the Seedance 2.5 Flash API? seedance-2.5-flash, with dots. The dashed seedance-2-5-flash is only the model page slug.

Does the Seedance 2.5 Flash API support 1080p? No. It accepts 480p and 720p. Send the same body with "model": "seedance-2.5" and "resolution": "1080p" for native 1080p.

How do I turn off audio in the Seedance 2.5 API? Set "generate_audio": false for a silent clip, or keep audio on and drop individual layers in the prompt, such as "no background music".

Can I use first frames and reference images in one Seedance 2.5 Flash request? No. image_urls and the reference_* fields must be sent in separate requests.

How long does a Seedance 2.5 Flash API task take? In PoYo's November 16, 2026 test, about two minutes for 4 seconds at 480p and under three minutes for 30 seconds at 720p, end to end. Poll or use a callback rather than holding a request open.

Am I charged if a Seedance 2.5 Flash task fails? No. Failed tasks are not charged, and their status shows credits_amount: 0.

Share: