Seedance 2.5 Request and Response Parameters

Verified on 2026-09-07 against Volcengine's official create task API (updated 2026-09-04), get task API (updated 2026-08-19), and the current ModelSell request/response converters.

Examples use the official model ID doubao-seedance-2-5-260628. With ModelSell, use an available model name and your ModelSell API key. Channel aliases and -max suffixes are not official Model IDs.

Task type guidance

omni_reference_task_type is an optional string request field, defaults to auto upstream, and is supported only by Seedance 2.5. It guides the interpretation of an omni-reference task; the model still determines the actual task type.

Use the top-level field in native requests. Generic requests also support the top-level field, with metadata.omni_reference_task_type as a fallback; the top-level value wins when both exist. Explicitly set the required edit/extend parameters. ModelSell validates the enum and related fields; the upstream validates the actual source-video duration.

Native request fields

Use POST /api/v3/contents/generations/tasks. Defaults and ranges below describe the official models. Field availability also depends on the selected channel. The built-in Volcengine channel and all six Seedance profiles forward these native options. Generic calls use metadata.<field> for advanced options; actual feature support still depends on the upstream model.

Other fields on the shared official API page—frames, seed, camera_fixed, draft, and service_tier: "flex"—apply to other models and do not establish support for Seedance 2.5. Use duration for integer-second output requests.

On 2026-09-09, option forwarding was completed against the official SDK request structure. Missing options do not inject defaults; explicit false and 0 are preserved. See Generic Video Format for the full mapping and last-frame example.

Media and roles

Image roles are reference_image, first_frame, or last_frame; video uses reference_video and audio uses reference_audio. First-frame, first/last-frame, and omni-reference modes are mutually exclusive. Do not combine frame roles with reference-media mode.

2.5 accepts up to 30 reference images, 10 videos, and 10 audio clips. Total video duration and total audio duration are each capped at 30 seconds. Individual reference videos are normally 2–30 seconds, or 4–30 seconds for editing; individual audio clips are 2–30 seconds. For 2.0, the corresponding limits are 9 images, 3 videos, 3 audio clips, and 15 seconds each for total video/audio duration.

Official image/audio inputs accept URLs, Base64 Data URLs, and supported asset:// references. Video accepts URLs or supported asset:// references, not Base64. Official limits are under 30 MB per image, at most 200 MB per video, 15 MB per audio clip, and 64 MB per request body; channels may impose smaller limits. The official 2.5 API accepts audio-only inputs, and ModelSell native/generic entry points accept valid media or draft content without a placeholder prompt; the upstream validates supported combinations.

Edit request

Replace the example URL with an accessible 4–30 second source video:

curl -X POST "$MODELSELL_BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "omni_reference_task_type": "edit",
    "content": [
      {"type": "text", "text": "Edit the reference video: replace the background with snowy mountains and preserve its motion and camera shots."},
      {"type": "video_url", "video_url": {"url": "https://example.com/reference-video.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": -1,
    "resolution": "720p",
    "generate_audio": true
  }'

For extension, keep the reference-video structure, use extend, explicitly ask to extend the source video forward or backward, keep ratio: "adaptive", and optionally set duration: 10. For a new video inspired by references, use reference and describe the new result.

Create and query responses

The minimum official create response contains only id; it does not mean generation has finished. ModelSell replaces the upstream ID with a public task ID. Poll with the returned id:

{"id":"task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6"}

curl "$MODELSELL_BASE_URL/api/v3/contents/generations/tasks/task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6" \
  -H "Authorization: Bearer $MODELSELL_API_KEY"

The following fields describe channels using Ark's native response. Availability depends on status, model, and channel. The official response schema does not list omni_reference_task_type; do not rely on it being echoed.

Official video URLs expire after 24 hours; 2.5 video URLs allow at most 100 downloads. Official queries cover the most recent 7 days. These are Ark upstream limits; other channels and ModelSell's local task retention can differ. Save successful outputs promptly.

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {"video_url": "https://example.com/seedance/result.mp4"},
  "created_at": 1788753600,
  "updated_at": 1788753660,
  "duration": 8,
  "framespersecond": 24,
  "resolution": "720p",
  "ratio": "16:9",
  "output_format": "mp4",
  "generate_audio": true,
  "usage": {"completion_tokens": 108900, "total_tokens": 108900},
  "error": null
}

Other channels and generic responses

Service Inference / Max native responses expose the upstream task fields at the top level. Success is completed, the URL is outputs[0], duration may be duration_seconds, and completion time is completed_at. Optional fields include usage, last_frame_url, prep, and a string error. This differs from Ark's content.video_url structure.

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "status": "completed",
  "model": "doubao-seedance-2-5-260628-max",
  "outputs": ["https://example.com/seedance/result.mp4"],
  "duration_seconds": 8,
  "error": null
}

GET /v1/videos/{task_id} returns normalized object: "video" with queued, in_progress, completed, or failed status. Read video_url / metadata.url, metadata.last_frame_url, metadata.usage, and metadata.output_format when returned upstream. GET /v1/video/generations/{task_id} retains the {code, data} envelope, with data.status and the upstream snapshot in data.data. The legacy task_id field may be absent; persist id. Some channels use this generic response even on the native route, so choose parsing rules for your channel. See Generic Video Format.

Immediate and asynchronous errors

{
  "id": "task_UPUfjg0S3UXekH2OgTZBXyqgGhsxgkp6",
  "status": "failed",
  "error": {
    "code": "InvalidParameter.TaskTypeMismatch",
    "message": "The detected task type does not match omni_reference_task_type."
  }
}

The message above is illustrative; actual wording comes from the upstream. Generic responses may normalize error.code to failed instead of preserving the original Ark code. Stop polling on failed, cancelled, or expired, and use a local deadline.