Seedance 2.5 API

What it does

Seedance 2.5 makes a video of 4 to 30 seconds, with a synchronized soundtrack by default, from a prompt and optional media. Everything goes in one list, input.content: text items carry the prompt, and each image_url, video_url and audio_url item names its role. The items you send choose the mode:

Every example below is a complete body for POST /v1/generations. Send the same body to POST /v1/estimates first: it is free, creates no task, holds no Credits, and refuses an invalid body with the same 422 as a create. The https://media.vizoapi.com/... files are public samples, so the examples run as they are; replace https://example.com/... with your own file or an uploaded ast_... asset ID.

Modes

Text to video

Only text items. Set ratio to one of 16:9, 4:3, 1:1, 3:4, 9:16 or 21:9; with adaptive (the default) the model picks one. duration is 4 to 30 seconds, default 5, or -1 to let the model choose.

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "A paper boat drifts across a still pond at dawn, mist on the water, slow push-in, soft natural light" }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }
}

First frame

The video starts on your image. Send one image_url with role first_frame and set ratio to adaptive: the output takes the image's aspect ratio, and any other ratio is refused (rule ratio_must_be_adaptive). The prompt describes what happens next.

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "The hominids step back as the sun rises behind the monolith, slow push-in" },
      { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" } }
    ],
    "ratio": "adaptive",
    "duration": 5
  }
}

First and last frame

The video moves from the first image to the last. Send at most one first_frame and one last_frame; a last_frame without a first_frame is refused (rule last_frame_needs_first_frame). Frames cannot be combined with any reference image, video or audio (rule frames_with_references).

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "The ring-shaped station slowly turns to face the camera as an amber planet rises behind it" },
      { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" } },
      { "type": "image_url", "role": "last_frame", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/ending.jpg" } }
    ],
    "ratio": "adaptive",
    "duration": 6
  }
}

Reference images

Up to 30 images with role reference_image give the model characters, objects, places or a style to reuse. Unlike frames, they do not fix the first or last picture, so any ratio works. Name them in the prompt by their order (see [Prompting tips](#prompting-tips)).

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "Shot 1: the black monolith from image 1 stands on a savanna at dawn. Shot 2: match cut to the ring-shaped space station from image 2, tumbling slowly in black space." },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" } },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" } }
    ],
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 8
  }
}

Reference video and audio

Reference videos (motion, camera, pacing) and reference audio (rhythm, voice, sound) can be mixed with reference images: up to 10 videos and 10 audio items. Audio may be the only media, as long as there is a text item. Any video_url item moves the task to the -video tier of its resolution, which bills the input video's seconds too (see [How it is billed](#how-it-is-billed)).

With a reference video, omni_reference_task_type says what to do with it: reference makes a new video, edit changes the source and extend lengthens it. If you omit it or send auto, the model infers the task from your prompt and media; the hold then covers the longest output, so set reference when you know you want a new video. omni_reference_task_type without any video is refused (rule task_type_without_video).

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "Follow the camera movement and pacing of video 1, set on the space station from image 1, cut to the beat of audio 1" },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" } },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" } },
      { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/beat.mp3" } }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 8,
    "omni_reference_task_type": "reference"
  }
}

Edit a video

Changes the source video and keeps its length: replace an object, restyle a scene, change the sound. Send the source as a video_url with role reference_video, 4 to 30 seconds long, and say the change in the prompt. duration must be -1 (rule duration_must_be_auto; leaving it out is refused too) and ratio must be adaptive.

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "Replace the black monolith with a tall crystal obelisk; keep everything else unchanged" },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" } }
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": -1,
    "omni_reference_task_type": "edit"
  }
}

Extend a video

Continues the source video. duration is 4 to 30 seconds or -1; ratio must be adaptive. Say in the prompt what happens next.

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "Continue the shot: the station drifts out of frame and the amber planet fills the screen" },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" } }
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 8,
    "omni_reference_task_type": "extend"
  }
}

Draft, then final

Try an idea cheaply at 480p, then turn the draft you like into a 1080p video with the same content, length and settings.

1. Send any of the bodies above with "draft": true and "resolution": "480p". Other resolutions, or no resolution at all, are refused (rule draft_needs_480p), and so is return_last_frame (rule draft_with_last_frame). A draft is a normal task, charged like any 480p video.
2. Within 7 days, send a body whose only content item is a draft_task with the draft's generation ID. Do not repeat the prompt, media, duration, ratio, seed, generate_audio, omni_reference_task_type, draft or bitrate_mode: the final video reuses the draft's (rules draft_task_alone, draft_task_field_not_allowed). resolution may be left out or set to 1080p (rule draft_task_resolution). return_last_frame, watermark and execution_expires_after are allowed.

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "text", "text": "A paper boat drifts across a still pond at dawn, mist on the water, slow push-in" }
    ],
    "draft": true,
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 5
  }
}

{
  "model": "seedance-2-5",
  "input": {
    "content": [
      { "type": "draft_task", "draft_task": { "id": "gen_01JD8Z7K3M9P4Q2R6S8T0V1W2X" } }
    ],
    "resolution": "1080p"
  }
}

The draft must be a succeeded "draft": true task of the same project. An ID the project does not have answers 404 resource_not_found; a task that is not a succeeded draft answers 404 draft_not_found; a draft older than 7 days answers 422 draft_expired.

Input limits

A media value is a public https URL (up to 4,000 characters) or an ast_... asset ID from your project. Plain http, private or local addresses, URLs with a user name or #fragment, and Base64 data are refused with 422 (rule bad_format). The model fetches a linked file itself, possibly some time after acceptance, so keep it reachable until the task closes; if it cannot, the task fails with input_media_unreachable. See Model inputs and media.

Output

A succeeded task lists one MP4 in result.outputs: take its asset_id and get a download URL with download an asset. With return_last_frame, result.last_frame_asset_id is the PNG. result.metadata reports what was made when the model returns it, such as duration, resolution, ratio and seed. Outputs are kept for 7 days. See Get results.

How it is billed

The input selects the tier: resolution alone, or resolution plus -video when content has any video_url. Images and audio never change the tier or the price, and neither do ratio, generate_audio, seed or watermark.

Input seconds are the length of all input videos together, rounded down, at most 30. When a video's length cannot be read at create, the hold counts 30 input seconds. When the model chooses the length (duration: -1, or a reference video with omni_reference_task_type omitted or auto), the hold counts 30 output seconds. An edit holds the source's length, rounded up.

Holds at 720p:

A 5-second draft holds 132.000 Credits at 480p, and its 1080p final holds 682.000 Credits: the final is a separate task, priced at 1080p (or 1080p-video when the draft had a video) for the draft's output and input seconds. A draft made with duration: -1 has its final hold 30 output seconds, as any automatic length does.

The hold is only the estimate. A succeeded task is charged from the usage the model reports, at the tier's rate, so price.charged can be below the hold (the rest is released) or above it, with no cap. Usage above the hold comes from your available balance; what it cannot cover is owed, and new creates get 402 balance_negative until a top-up. A failed, canceled or unresolved task is not charged. Send the body to POST /v1/estimates to see the exact hold and its basis (output_seconds, input_seconds, billed_seconds, auto). See Billing.

Errors and behaviors

Moderation is always on; no field turns it off. Each task has a deadline, execution_expires_after: 3600 to 259200 seconds (1 to 72 hours) from acceptance, default 86400. A task still unfinished then closes as unresolved, releases its hold and is not charged; if its result arrives later, it is added at no charge and late_result_available becomes true. See Errors and Get results.

Prompting tips

• Name reference media by kind and order in content: "image 1", "image 2", "video 1", "audio 1". Say what to take from each: "the character from image 1", "the camera movement of video 1", "the rhythm of audio 1".
• Write the shot, not just the subject: subject, action, setting, camera movement, light and style, in that order. For several shots, number them ("Shot 1: …, Shot 2: …") and give each its own camera move.
• Describe the sound you want when generate_audio is on: ambience, effects, music or none, and any spoken line in quotes.
• For an edit, say exactly what changes and what stays ("keep everything else unchanged"). For an extension, describe what happens next, not what is already in the video.
• With first and last frames, describe the motion between them; the frames already fix the start and end.
• Put settings in fields, never in the prompt: --ratio 16:9 style flags are refused.
• Draft first at 480p while you iterate on the prompt, then upgrade the draft you like to 1080p.

Pricing

Your input selects the tier. Video is billed per second of output; a tier with input video also counts the input seconds.

Rules

• Apart from a draft_task request, content needs at least one text, image or video item.
• Every image, video and audio item in content names its role.
• Input limits: up to 30 images, 10 videos and 10 audio items in content, with no limit on the total. Each video and audio item runs 2 to 30 seconds, and an edit source video 4 to 30 seconds. Videos add up to at most 30 seconds, and audio to at most 30 seconds. Lengths are checked before the task is created when the file can be measured (422 input_duration_out_of_range).
• Image pixel size and aspect ratio, and video resolution and frame rate, are not checked when the request is made: the model checks them when the task runs, and a file it refuses usually fails the task with input_media_invalid (otherwise generation_failed); the task is not charged.
• first_frame and last_frame images (at most one each) cannot be combined with reference images, videos or audio, and a last_frame needs a first_frame.
• ratio must be adaptive for first-frame, edit and extend input.
• omni_reference_task_type may be omitted or auto with a reference video; it is not allowed without video. Automatic task selection holds the maximum output length to cover edit or extend; for edit, duration must be -1.
• draft set to true needs resolution 480p and cannot be combined with return_last_frame.
• A draft_task item must be the only item in content, and names a succeeded draft of your project from the last 7 days.
• A draft_task request reuses the draft's settings: it does not accept duration, ratio, seed, generate_audio, omni_reference_task_type, draft or bitrate_mode, and resolution can only be 1080p.
• Prompt text must not contain inline --flag parameters.

Input fields

Send these fields in input. A field the table does not list is refused with HTTP 422 invalid_input.

Example

A complete create request, the 202 answer and the task once it has succeeded.

Request

curl https://api.vizoapi.com/v1/generations \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2-5",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A paper boat drifting on a pond at dawn, slow dolly in"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  },
  "metadata": {
    "client_reference": "my-unique-reference-1"
  }
}'

import os, requests

# Send once: do not retry this request automatically.
task = requests.post(
    "https://api.vizoapi.com/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "model": "seedance-2-5",
      "input": {
        "content": [
          {
            "type": "text",
            "text": "A paper boat drifting on a pond at dawn, slow dolly in"
          }
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5
      },
      "metadata": {
        "client_reference": "my-unique-reference-1"
      }
    },
    timeout=60,
).json()
print(task["id"], task["status"])

// Send once: do not retry this request automatically.
const res = await fetch("https://api.vizoapi.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "seedance-2-5",
    "input": {
      "content": [
        {
          "type": "text",
          "text": "A paper boat drifting on a pond at dawn, slow dolly in"
        }
      ],
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    },
    "metadata": {
      "client_reference": "my-unique-reference-1"
    }
  }),
});
const task = await res.json();
console.log(task.id, task.status);

Response

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "seedance-2-5",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "processing",
  "execution_status": "processing",
  "delivery_status": "pending",
  "billing_status": "pending",
  "version": 1,
  "price": {
    "unit": "credit",
    "estimated": "283.000",
    "reserved": "0.000",
    "charged": "0.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": null,
  "error": null,
  "result": null
}

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "seedance-2-5",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "succeeded",
  "execution_status": "succeeded",
  "delivery_status": "ready",
  "billing_status": "settled",
  "version": 4,
  "price": {
    "unit": "credit",
    "estimated": "283.000",
    "reserved": "0.000",
    "charged": "283.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": "2026-11-08T09:01:31Z",
  "error": null,
  "result": {
    "asset_id": "ast_01JD8Z9M2C4V",
    "outputs": [
      {
        "index": 0,
        "asset_id": "ast_01JD8Z9M2C4V",
        "content_type": "video/mp4"
      }
    ]
  }
}