> ## Documentation Index
> Fetch the complete documentation index at: https://docs.floodgate.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance video API

> Generate Seedance videos with text, frames or reviewed media references. Poll, list and cancel tasks, download results, and check limits and token charges.

Use Seedance with text, frame images or reviewed media references. Keep the public task ID for status, cancellation and downloads.

## Operations and limits

| Method | Path | Purpose |
| - | - | - |
| POST | `/api/v3/contents/generations/tasks` | Submit |
| GET | `/api/v3/contents/generations/tasks/{task_id}` | Native polling |
| GET | `/api/v3/contents/generations/tasks` | List owned Seedance tasks |
| DELETE | `/api/v3/contents/generations/tasks/{task_id}` | Request cancellation |
| GET | `/v1/videos/{task_id}` | Compatible polling, when available |
| GET | `/v1/videos/{task_id}/content` | Download |

Use only operations available for your exact model/group in [Model Square](https://floodgate.dev/models). Drafts, editing, extension, tools and asset management are outside this reviewed reference.

| Models | Groups | Duration |
| - | - | - |
| `doubao-seedance-2-0-260128` | `Seedance-2` | `-1` for automatic, or 4 to 15 seconds |
| `doubao-seedance-2-0-fast-260128`, `doubao-seedance-2-0-mini-260615` | `Seedance-1`, `Seedance-2` | `-1`, or 4 to 15 seconds |
| `doubao-seedance-2-5-260628` | `Seedance-2` | `-1`, or 4 to 30 seconds |

| Field | Limits |
| - | - |
| `model`, `content` | Required; accepted model ID and content parts |
| `content[].text` | At most one text part, 1 to 7,000 characters |
| Image references | Up to 9 for 2.0/Fast/Mini, 30 for 2.5 |
| Video or audio references | Up to 3 of each for 2.0/Fast/Mini, 10 of each for 2.5 |
| Total `content` parts | 1 to 16 for 2.0/Fast/Mini, 1 to 51 for 2.5 |
| `resolution` | Selected offering's allowed values; `Seedance-1` excludes `480p` |
| `ratio` | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive` |
| `generate_audio`, `return_last_frame`, `watermark` | Boolean |
| `output_format` | 2.5 only: `mp4` or `mov` |

Media parts use `type: "image_url"`, `"video_url"` or `"audio_url"` with a nested `url`. Roles are `first_frame`, `last_frame`, `reference_image`, `reference_video` or `reference_audio`.

A last frame requires a first frame. Frame inputs cannot mix with reference images, video or audio. Seedance 2.5 frames require `adaptive` ratio; 2.0 audio references require an image or video.

HTTPS and validated asset URIs are supported. Embedded image data URLs allow JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC or HEIF up to 30 MiB each. Embedded WAV/MP3/MPEG audio is limited to 15 MiB each. Video data URLs and multipart uploads are unsupported. Other URL media-size limits and omitted defaults are undocumented by the reference metadata.

## Submit

```bash theme={null}
curl --fail-with-body https://api.floodgate.dev/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"doubao-seedance-2-0-260128","content":[{"type":"text","text":"A quiet forest beside a lake"}],"duration":5,"resolution":"720p"}'
```

```json theme={null}
{"id":"task_example","task_id":"task_example","object":"video","model":"doubao-seedance-2-0-260128","status":"queued","progress":0,"created_at":1700000000}
```

## Poll and download

Set `TASK_ID` to the returned `id`:

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"
```

Pending states are `queued` and `running`. Terminal states are `succeeded`, `failed`, `cancelled` and `expired`. Read `content.video_url` only after `succeeded`.

```json theme={null}
{"id":"task_example","status":"succeeded","content":{"video_url":"/v1/videos/task_example/content"},"usage":{"completion_tokens":1000,"total_tokens":1000}}
```

```json theme={null}
{"id":"task_example","status":"failed","error":{"code":"task_failed","message":"Video generation failed"}}
```

After success, download with authentication. Use a `.mov` filename for MOV output:

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" --output video.mp4
```

## List and cancel

```bash theme={null}
curl --fail-with-body 'https://api.floodgate.dev/api/v3/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded' \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"

curl --fail-with-body -X DELETE "https://api.floodgate.dev/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"
```

Listing returns your Seedance tasks across groups. `page_num` is 1 to 1,000,000 and defaults to 1. `page_size` is 1 to 100 and defaults to 20. `filter.status` accepts the native statuses above.

```json theme={null}
{"items":[{"id":"task_example","status":"succeeded","content":{"video_url":"/v1/videos/task_example/content"},"usage":{"completion_tokens":1000,"total_tokens":1000}}],"total":1,"page_num":1,"page_size":20}
```

Accepted cancellation returns HTTP 202:

```json theme={null}
{"id":"task_example","status":"cancel_requested"}
```

This acknowledges the request. Continue polling for a terminal state. It does not itself release reserved funds. A `409` means the task already finished or submission is still being confirmed.

## Errors and billing

Seedance settles using verified completion tokens. Reference video affects the selected rate. Follow-ups keep the original task's group and pricing. Cancellation releases funds only after a trusted terminal result. Missing final usage can leave settlement pending.

Check `error` on terminal failure. Check content combinations and model/group limits on `400`; unfinished downloads return `400`, expired results `410`. Keep the task ID after timeouts or `submission_uncertain`. See [shared video errors](https://docs.floodgate.dev/videos.md#errors-and-retries).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.