# Seedance 2.5 Flash — /videos/generations

Seedance 2.5 Flash 视频生成接口（字节跳动），Seedance 2.5 的 Flash 版，按秒计费，单价低于 Seedance 2.5。异步任务：提交后立即返回任务号，再查询或用 Webhook 拿到 MP4。支持 4–30 秒、480P / 720P、5 种画面比例；参考图（最多 10 张）、参考视频（最多 5 段）和参考音频（最多 5 段）可以放在同一个请求里，成片自带声音。失败不收费。

**端点:** `POST https://kovapi.com/v1/videos/generations`

## 快速开始

三步跑通：提交任务 → 查询结果 → 拿到视频链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

**第 1 步 · 提交任务（立刻返回任务号，HTTP 202）**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-flash", "prompt": "雨夜的霓虹街道，一只纸船顺着积水漂过，镜头低角度跟随，水花和倒影清晰", "duration": 5, "resolution": "720P", "size": "16:9"}'
```

返回（HTTP 202）

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedance-2.5-flash"
}
```

**第 2 步 · 每 5–10 秒查询一次，直到 `status` 变成 `succeeded` 或 `failed`**

```
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功时的返回

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedance-2.5-flash",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.5-flash"}
}
```

**第 3 步 · `data[0].url` 就是成片（MP4），保留 7 天；需要长期使用，请下载到你自己的存储。**

**完整示例（Python：提交 → 等待 → 保存到本地）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "seedance-2.5-flash",
    "prompt": "雨夜的霓虹街道，一只纸船顺着积水漂过，镜头低角度跟随，水花和倒影清晰",
    "duration": 5,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 10 秒查询一次，最多等一小时
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载视频
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedance-2.5-flash.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

排队时，查询结果里还有 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计还要等几秒）。超过你设的等待时间也不要重新提交：任务还在，稍后用同一个任务号接着查。

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 规格速览

| 时长 | 4–30 秒 |
| --- | --- |
| 分辨率 | 480P / 720P |
| 画面比例 | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 |
| 参考图 | 最多 10 张 · 用作参考（人物、场景、风格），不作首帧 |
| 参考视频 | 最多 5 段，合计不超过 30 秒 |
| 参考音频 | 最多 5 段，每段不超过 30 秒 |
| 声音 | 固定带声音（对白、音效和配乐由模型生成），不能关 |
| 提示词长度 | 最多 11,000 个字符（中英文一样计） |
| 计费方式 | 按秒：每秒单价 × 下单的秒数 |

## 请求参数

`POST /v1/videos/generations` 的请求体（JSON）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 id：`seedance-2.5-flash`。 |
| prompt | string | 是 | 画面、镜头和动作的描述，最多 11,000 个字符（中英文一样计）。 |
| duration | integer | 否 | 时长（秒），4–30 之间的整数，不传为 4。也可以写作 `seconds`。 |
| resolution | string | 否 | 分辨率：480P / 720P，不传为 720P。请带上 P（`720` 这样不带 P 的写法会被拒绝）。 |
| size | string | 否 | 画面比例：16:9 / 9:16 / 1:1 / 4:3 / 3:4，不传为 16:9。也可以写作 `aspect_ratio`。 |
| images | array | 否 | 参考图，最多 10 张，用来定人物、场景和风格，不会被当成首帧。在提示词里按传入顺序用 `@Image1`、`@Image2` 点名。只有一张时也可以放在 `image`。 |
| video_references | array | 否 | 参考视频，最多 5 段，合计不超过 30 秒。可以和参考图一起传（照片定人物外貌，视频定动作和运镜），在提示词里用 `@Video1` 点名。每段可以是公网链接，也可以是 `data:video/mp4;base64,...`（mp4 / mov，单段不超过 50MB，整个请求不超过 100MB）。链接要能直接下载到文件本身；YouTube、B 站、抖音、网盘分享页这类网页链接不行，提交时会直接返回 400。 |
| audio_reference | array | 否 | 参考音频，最多 5 段，每段不超过 30 秒（按实际时长算，30.1 秒也会被拒），用公网 http(s) 链接，要和参考图或参考视频一起传，在提示词里用 `@Audio1` 点名。链接要能直接下载到文件本身；YouTube、B 站、抖音、网盘分享页这类网页链接不行，提交时会直接返回 400。 |
| audio | boolean | 否 | 成片固定带声音（对白、音效和配乐由模型按提示词生成），不能关闭；传 `false` 不起作用。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址，见下文的 Webhook。 |
| n | integer | 否 | 每个任务出 1 条视频，不用传。传了大于 1 的值也只出 1 条，但提交时会按 n 条预扣，任务结束后退回多扣的部分。 |

其他字段（如 `seed`、`negative_prompt`、`fps`、`watermark`）不会转发，也不影响价格；成片一律是 MP4，通过 `url` 返回。

## 价格

按秒计费：费用 = 所选分辨率的每秒单价 × 下单的秒数。提交时按这个金额预扣，成功按同样的金额结算，失败全额退回。1 积分 = $0.005。

| 分辨率 | 积分 / 秒 | 美元 / 秒 | 5 秒一条 |
| --- | --- | --- | --- |
| 480P | 12 | $0.06 | $0.30 |
| 720P | 24 | $0.12 | $0.60 |

带参考视频的单按下表计价：计费秒数 = 参考视频秒数 + 输出秒数，参考音频不计费。

| 分辨率 | 积分 / 秒 | 美元 / 秒 | 5 秒输出 + 5 秒参考视频 |
| --- | --- | --- | --- |
| 480P | 7 | $0.035 | $0.35 |
| 720P | 14 | $0.07 | $0.70 |

## 参考素材

- 参考图最多 10 张，用来定人物、场景、产品和风格。Seedance 不把图片当首帧：想让某张图里的人物或物品出现在画面里，就在提示词里点名它（`@Image1`、`@Image2` …，按传入顺序编号）。

- 参考视频最多 5 段（合计 30 秒以内），用来定动作、运镜和节奏；参考音频最多 5 段（每段不超过 30 秒，30.1 秒也会被拒），用来定说话的声音或配乐，要和参考图或参考视频一起传。三种素材可以放在同一个请求里，分别用 `@Image1` / `@Video1` / `@Audio1` 点名。

- 支持真人人脸参考图，无需遮挡。请确保你有权使用图中人物的肖像。

- 每张参考图的宽和高都要在 300–6000 像素之间，宽高比在 0.4–2.5 之间（195×195 的小图或 1:3 的长条图都不行）。不符合的在提交时就返回 400 `reference_image_dimensions`，写明是第几张、实际尺寸多少，不计费。

- 每张图可以是公网图片链接、`data:` URI 或 base64，单张不超过 16MB，多张用数组放在 `images` 里。提交时我们先把图片转存好再排队；读不到的图片会直接返回 400，`message` 写明是第几张，这一单不计费。

- 我们转存的参考素材和成片都保留 7 天。

**参考图 + 参考视频一起用**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-flash", "prompt": "@Image1 的女孩在 @Image2 的街道上，跳 @Video1 里的舞", "images": ["https://example.com/character.png", "https://example.com/street.png"], "video_references": ["https://example.com/dance.mp4"], "duration": 5, "size": "16:9"}'
```

`@Image1` 是第 1 张参考图，`@Video1` 是第 1 段参考视频。带参考视频时，参考视频的秒数也计费，单价见价格表。

## 内容要求

Seedance 的每个任务都要经过内容审核，范围包括提示词、参考素材和生成的成片，画面和声音都审。没通过审核的任务以 `content_policy` 失败，不收费。

### 什么时候审

提交时先审提示词和参考素材，成片生成后再审一次画面和声音。所以被拒的结果可能在提交后几秒内返回，也可能要等到渲染结束，半小时以上才返回。任务以 `status` 为 `failed`、`error.code` 为 `content_policy` 结束，就是没通过审核；用 Webhook 会收到 `video.failed` 事件。

### 不收费

被拒的任务不扣费：提交时预扣的金额在任务结束时全额退回，调用日志里也显示未计费。

### 声音

成片的声音（对白、旁白、歌声和音效）由模型按提示词生成，和画面一起审核：提示词里写的台词、旁白和歌词会被念出来或唱出来。不需要人声的片子，提示词里就别写台词和歌词。这个型号每条成片都带声音，不能关闭；请求里传 `audio: false` 不起作用。上传的参考音频同样要过审，受版权保护的音乐作参考音频可能被拒。声音没通过时，`error.param` 为 `audio`，message 会写明是生成的声音还是上传的参考音频。

### 常被拒的内容

- 色情、裸露或性暗示，包括 AI 生成或合成的画面

- 血腥、残忍、自残，以及中枪、流血等暴力伤害

- 枪支、爆炸物、毒品

- 涉及未成年人的性化内容一律不行；未成年人和烟酒、毒品或危险行为同框也会被拒

- 政治人物、明星、体育和商界名人等公众人物的形象或声音，包括长得很像的人物

- 受版权保护的角色和 IP 形象，例如迪士尼、漫威角色

- 仇恨、歧视内容和虚假新闻

### 长分镜脚本

一条成片只要有一个镜头违规，整条都会被拒，长分镜脚本最容易踩到：动作戏里的枪战和流血特写、未成年人出现在饮酒或吸烟的场景里，都会让整条失败。提交前通读一遍，删掉或改写这类镜头。

### 真人肖像

用真人照片作参考，需要你有权使用其肖像。

### 被拒之后

原样重新提交还会被拒。先找出可能违规的那部分，改写提示词或更换参考素材，再重新提交。

错误码: `content_policy` · `status: failed`

`upstream_line_unavailable`: 生成服务过载或可用资源不足时，返回 upstream_line_unavailable。本次失败不计费，预扣积分退还，请稍后重试。该错误没有指出具体的参数或素材问题。明确的时长限制、素材读取失败和审核拒绝仍分别返回 duration_rejected、reference_unreadable 和 content_policy；请按对应提示调整。

## 任务状态与返回字段

`GET /v1/videos/jobs/{id}` 返回这些状态，各字段的说明见 [异步任务](https://docs.kovapi.com/guide/async-jobs#fields)。每 5–10 秒查一次，或者用下面的 Webhook 等推送。查询不收费，同一个账号的任何 Key 都能查。

| 状态 | 含义 |
| --- | --- |
| queued | 排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 `data[0].url`，计费明细在 `usage`。 |
| failed | 失败。原因在 `error`，预扣的积分已全额退回。 |

- `processing` 有时会回到 `queued`：例如服务繁忙、成片正在重新取回，或者服务重启。任务没能完成时，网关可能自动重新生成；无论重试几次，一个任务只扣一次费用。

- 同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，视频链接保留 7 天。

## 出片时间

720P 一般 4–8 分钟，480P 一般 2–3 分钟；时长越长越久，高峰排队时会更久。

## 错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://docs.kovapi.com/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | invalid_request | 参数不合法：时长、分辨率、比例或素材数量超出这个模型的范围，提示词太长，参考图或参考视频读不到，或者给固定带声音的模型传了 `audio: false` 等。`message` 写明原因。 | 按 `message` 修改后重新提交。 |
| 400 | invalid_callback_url | `callback_url` 不是公网的 http(s) 地址，或超过 2000 个字符。 | 换成能从公网访问的地址。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://docs.kovapi.com/api) 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://kovapi.com/status)。 |
| 503 | service_unavailable | 我们这边临时出错，例如保存参考素材失败。这一单没有创建任务，也没有扣费。 | 稍后重试。 |
| 400 | reference_image_dimensions | 参考图尺寸不符合：某张图的宽或高不在 300–6000 像素之间，或宽高比不在 0.4–2.5 之间（报错里写明第几张和实际尺寸） | 换一张图，或把这张图放大 / 裁成符合要求的尺寸后重新提交；不计费。 |

### 任务失败（`status` 为 `failed`）

| code | 什么时候出现 | 怎么办 |
| --- | --- | --- |
| content_policy | 视频：提示词、参考素材，或生成的画面 / 声音没通过内容审核（声音被拦时 `param` 为 `audio`）。 Wan 标准版和 Prime：输入素材未通过审核。`error.reason` 为 `FaceDetectionSuspect`（疑似真人面部）或 `DataInspectionFailed`（输入内容审核未通过）。`error.message` 说明原因和调整建议；失败任务未计费。 | 改写提示词或更换素材后再提交；原样重交还会被拒。 |
| request_rejected | 视频：上游没有接受这次请求，并说明了原因；`message` 里附上游原话（例如某个参考素材无法处理）。 | 按原话修改提示词或参考素材后再提交；原样重交通常还会失败。不计费。 |
| render_failed | 视频：这次没有生成出成片，多为偶发。 | 原样重新提交通常就能成功。 |
| invalid_material | 视频：上游认为输入素材有问题。这是一个笼统的报错，也常是偶发。 | 先原样重交；反复出现再检查参考素材和提示词长度。 |
| duration_rejected | 视频：时长没有被接受。最常见的是参考音频或参考视频超过上限，哪怕只超零点几秒。 | 把参考音频 / 视频剪到上限以内再提交；原样重交还会失败。 |
| reference_unreadable | 视频：模型下载不到参考图、视频或音频，常见是 YouTube、网盘分享页这类网页链接。 | 换成能直接下载到文件的链接，或者在 Playground 本地上传；原样重交还会失败。 |
| render_timeout | 视频：排队或渲染时间过长，上游放弃了这一单。 | 重新提交。 |
| wait_timeout | 视频：超过 120 分钟仍未生成结果，按超时处理，积分全额退还；之后如果生成成功，视频免费交付。 | 重新提交。 |
| upstream_unstable | 视频：渲染过程中连接中断。 | 重新提交。 |
| result_fetch_failed | 视频已经生成，但我们反复下载或保存成片都没有成功。 | 重新提交。 |
| upstream_error | 其他失败：自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等，`message` 写明具体情况。 | 通常重新提交就能成功。 |

请按 `code` 判断，不要匹配 `message` 的文字。遇到不认识的 `code`（或者没有 `code`），按 `upstream_error` 处理：重新提交通常就能成功。失败的任务一律全额退款。

## 用 Webhook 代替轮询

提交时加上 `callback_url`，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 [Webhook 文档 →](https://docs.kovapi.com/webhooks)

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-flash", "prompt": "雨夜的霓虹街道，一只纸船顺着积水漂过，镜头低角度跟随，水花和倒影清晰", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```
