# Seedance 视频

> Seedance 2.0 / 2.5 原生视频生成、样片转正式视频、联网搜索及任务列表、查询与取消/删除。

Base URL：`https://platform.sgt.site/volcengine`

**受理与恢复：**原生提交在发送前持久保存平台任务并冻结资金。发送后断连、超时、5xx、截断成功响应或缺任务 ID 时保持待核对，不自动重复提交或释放资金，且不依赖重试次数设置。错误诊断中的 `task_id` 和 `request_id` 可定位同一平台任务；使用原查询路径继续核查。未取得可靠上游 ID 时由管理员按这些标识核对，不通过重新 POST 猜测恢复。原生 `Idempotency-Key` 尚无跨请求重放保证，每次提交仍是一次独立生成尝试。明确未发送或被上游拒绝时才释放本次预留；生成状态与账务结算状态分别判断。

将 MiniMax H3 的任务 ID 用于本页 Seedance 单任务查询时返回 HTTP 404；请使用该任务提交时对应的 H3 查询路径，不要重新生成。

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

模型自动发现使用相对路径 `GET /models` 或 `GET /v1/models`（均支持尾斜杠），与 `GET /api/v3/models` 返回相同的授权目录，不限于火山渠道模型。这是平台兼容扩展，不是火山官方列表 API；使用平台虚拟密钥，空目录返回 HTTP 200、`data: []`，不提交生成任务、预留预算或扣费。SDK 如自行追加 `/v1/models`，不要在 Base URL 中重复加入 `/v1`；生成仍使用下表原生任务路径。

| 方法 | 路径 |
| --- | --- |
| POST | `/api/v3/contents/generations/tasks` |
| GET | `/api/v3/contents/generations/tasks` |
| GET | `/api/v3/contents/generations/tasks/{task_id}` |
| DELETE | `/api/v3/contents/generations/tasks/{task_id}` |

<a id="native-seedance-section-1"></a>

## 2.1 路径及模型范围

| model | resolution | duration |
| --- | --- | --- |
| `doubao-seedance-2-0-260128` | `480p/720p/1080p/4k` | 整数 4–15，或 -1 |
| `doubao-seedance-2-0-fast-260128` | `480p/720p` | 整数 4–15，或 -1 |
| `doubao-seedance-2-0-mini-260615` | `480p/720p` | 整数 4–15，或 -1 |
| `doubao-seedance-2-5-260628` | `480p/720p/1080p` | 整数 4–30，或 -1 |

分辨率使用表中大小写。`duration=-1` 或省略时由模型自选时长，平台先按合法时长与输入范围估计 token 并冻结预算，完成后按 `usage.completion_tokens` 等可信实际用量结算。整数 `duration` 是时长约数，不能代替实际 token 用量。

<a id="native-seedance-section-2"></a>

## 2.2 请求字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，精确模型名称 |
| `content` | array | 原生多模态输入；至少有有效文本或支持的素材 |
| `resolution` | string | 默认 `720p` |
| `ratio` | string | `16:9/4:3/1:1/3:4/9:16/21:9/adaptive`，默认 `adaptive`；Seedance 2.5 的首帧/首尾帧、视频编辑、视频延长只支持 `adaptive` |
| `duration` | integer | 见模型表；-1 表示由模型在范围内自选；Seedance 2.5 默认 -1，视频编辑只能为 -1 |
| `generate_audio` | boolean | 默认 `true`，生成与画面同步的单声道音频；`false` 为无声视频 |
| `watermark` | boolean | 默认 `false`；`true` 时右下角显示“AI 生成” |
| `return_last_frame` | boolean | 默认 `false`；`true` 时查询结果返回尾帧 JPEG（`content.last_frame_url`），可作为下一段视频的首帧 |
| `seed` | integer | 随机种子 [-1, 2147483647]；官方文档标注为 Seedance 1.0 系列参数，2.x 传入不保证生效 |
| `execution_expires_after` | integer | 任务超时秒数，默认 172800（48 小时），范围 [3600, 259200]；超时未完成的任务标记为 `expired` |
| `priority` | integer | 官方范围 [0, 9]，默认 0；平台共享 Endpoint 仅允许省略或 0。非零需要事先验证的企业独占 Endpoint 与允许范围 |
| `safety_identifier` | string | 终端用户标识，不超过 64 个字符，建议传哈希后的用户 ID |
| `omni_reference_task_type` | string | 仅 2.5，`auto`（默认）/`reference`/`edit`/`extend`；指定后提交时即校验对应任务类型的限制 |
| `output_format` | string | 仅 2.5，`mp4`（默认）或 `mov`（高色彩精度，部分播放器不兼容） |
| `draft` | boolean | 默认 false；仅 2.5 可设 true，且必须显式使用 480p；详见样片流程 |
| `tools` | array | 可选 `[{"type":"web_search"}]`，只接受纯文本输入，需有有效工具价格和预留配置 |
| `callback_url` | string | 可选，平台允许的 HTTPS 接收地址；通知基于平台已持久化的任务状态 |

生成参数按本页规则传给模型；`callback_url` 由平台保存和投递，不转发给上游。使用 `omni_reference_task_type`、`output_format`、`priority` 等选项时，须遵守表中对应的型号与取值限制。

本期 2.x 型号不接受 `frames` 或 `service_tier=flex`。平台也不接受在提示词末尾追加 `--rs`、`--dur` 等弱校验参数；分辨率、时长和比例请使用对应字段。工具配置只接受本页列出的字段，不能额外传入未经声明的工具上限选项。

<a id="native-seedance-section-3"></a>

## 2.3 content 格式

| type | 素材字段 | role |
| --- | --- | --- |
| `text` | `text` | 不需要 |
| `image_url` | `image_url.url` | `first_frame / last_frame / reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |
| `draft_task` | `draft_task.id` | 不填；仅一项，使用同主体、同协议的成功样片平台任务 ID |

首帧、首尾帧、多模态参考（参考图/视频/音频）是三种互斥的输入方式，不能混用。只传首帧时 `role` 可写 `first_frame` 或不填；首尾帧两张可以相同，比例不一致时以首帧为准裁剪尾帧。素材格式、尺寸、时长和数量要求见 2.7。

<a id="native-seedance-section-4"></a>

## 2.4 文生视频

以下 Bash / curl 示例展示完整地址、鉴权与请求体。将 `KEY` 替换为自己的完整虚拟密钥：

```bash
BASE_URL="https://platform.sgt.site/volcengine"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"doubao-seedance-2-0-260128","content":[{"type":"text","text":"镜头缓慢推进，清晨阳光照亮白色陶瓷杯"}],"resolution":"720p","ratio":"16:9","duration":5,"generate_audio":false}'
```

下面是同一接口的其他请求体：

```json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "镜头缓慢推进，清晨阳光照亮桌上的白色陶瓷杯"}
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
```

首尾帧示例：

```json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "从第一张画面自然过渡到最后一张画面"},
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/first.png"},
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/last.png"},
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": false,
  "watermark": false,
  "return_last_frame": true
}
```

参考视频模式示例：

```json
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "参考视频1的运镜，生成日落时的海边场景"},
    {
      "type": "video_url",
      "video_url": {"url": "https://media.example.com/reference.mp4"},
      "role": "reference_video"
    }
  ],
  "omni_reference_task_type": "reference",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "output_format": "mp4"
}
```

<a id="native-seedance-section-5"></a>

## 2.5 提交和查询响应

提交成功：

```json
{"id": "task_example"}
```

查询：

```bash
BASE_URL="https://platform.sgt.site/volcengine"
curl -X GET "$BASE_URL/api/v3/contents/generations/tasks/task_example" \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

成功结果示例：

```json
{
  "id": "task_example",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://media.example.com/generated-video.mp4"
  },
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9"
}
```

单任务查询与原生列表都根据平台已保存的任务事实返回状态，不保证每次读取都已看到厂商的最新变化。状态含义如下：

| `status` | 含义与下一步 |
| --- | --- |
| `queued` | 已受理或排队，继续查询；若带提交待核对的 `diagnostic`，按诊断核对原任务，不重新 POST |
| `running` | 生成中，继续查询 |
| `succeeded` | 生成成功，检查 `content` 中实际返回的产物；用量与账务仍需分别判断 |
| `failed` | 生成失败，读取安全错误摘要，核对原因与账务后再决定是否发起新任务 |
| `cancelled` | 已取消；以保存的上游状态或平台确认的取消结果为准，不要求错误信息包含 `cancel` 字样 |
| `expired` | 上游任务超时，属于终态；不会被改写成 `failed`，也不表示下载链接刚刚过期 |

单任务和列表保留已存的 `expired` / `cancelled`；通过统一媒体接口提交的 Seedance 任务也使用这两个终态。各协议的任务仍应使用提交时对应的查询入口，不能混用任务 ID。终态本身不代表已退款或费用为零。

响应字段按以下条件出现，调用方不要把缺失字段当成空值、零值或承诺稍后一定补齐：

| 字段 | 返回条件与含义 |
| --- | --- |
| `id` | 平台任务 ID，用于后续查询；不返回上游任务 ID |
| `model` | 非成功单任务与列表使用提交模型 ID；成功单任务保留已存响应中的模型标识，缺失时补提交模型 ID |
| `status` | 上表中的任务状态；调用方应兼容未来增加的状态值 |
| `error` | `failed`、`expired` 及部分 `cancelled` 响应包含 `code/message` 安全摘要；平台确认取消的精简响应可能不带，不原样透出上游错误 |
| `diagnostic` | 在失败、受理待核对或已有诊断事件等情况下附带平台诊断；不是每次查询都有 |
| `content` | 成功单任务按已存结果返回；`video_url`、`cover_url`、`last_frame_url` 仅在结果确实包含时出现，不能假定三者都有；非成功单任务不补造产物 |
| `created_at`、`updated_at`、`duration`、`resolution`、`ratio`、`seed` 等 | 成功单任务按已存结果返回；非成功单任务通常只有标识、状态和适用的错误/诊断。列表会补入已存的时间和受支持结果字段，因此两种查询的字段集合可能不同 |
| `usage` | 只有已保存相应用量证据时出现，不保证每种状态都有；表示模型用量，不等于人民币费用 |

<a id="native-seedance-h-db5aeb03"></a>

### 下载视频与附属图片

| 字段 | 类型与出现条件 | 用途 |
| --- | --- | --- |
| `content.video_url` | string，成功结果确有视频时 | 主视频，必须检查非空后下载 |
| `content.cover_url` | string，可选，仅上游提供时 | 封面，与主视频分别保存 |
| `content.last_frame_url` | string，可选，请求 `return_last_frame=true` 且结果提供时 | 尾帧图片；按真实 MIME/字节识别 JPEG/PNG |

未出现的可选字段不是空文件。视频可能是 MP4（`video/mp4`）或 MOV（`video/quicktime`），以文件头和明确内容类型命名；不从 `video_url` 字段名推断格式。MOV/MP4 容器及内部编码的播放能力取决于客户端，改扩展名不是转码。未知格式保留 `.bin` 并提示。

先把[快速开始](overview.md#overview-h-600de8a7)中的 Python 脚本保存为同目录的 `media_client.py`，复用其中不携带密钥的下载函数。保存已有任务查询响应后再下载（不会提交生成）：

```bash
curl -fSs "$GATEWAY_ORIGIN/volcengine/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $KEY" -o seedance-task.json
```

```python
import json
from pathlib import Path
from media_client import DeliveryPending, save_file


def download_seedance(result, folder="output"):
    content = result.get("content") or {}
    if result.get("status") != "succeeded" or not content.get("video_url"):
        raise DeliveryPending("尚无可读主视频；保留 ID，继续查询原任务")
    saved = []
    for field, kind in [("video_url", "video"), ("cover_url", "cover"), ("last_frame_url", "last_frame")]:
        if field in content:
            saved.append(save_file(content[field], Path(folder) / f"seedance-{kind}"))
    return saved


if __name__ == "__main__":
    result = json.loads(Path("seedance-task.json").read_text(encoding="utf-8"))
    download_seedance(result)
    print("文件已保存；客户端播放与账务须分别核对")
```

空地址、HTTP 错误、空文件或字节不完整会报错；未完成文件只保留 `.part`。遇到这些错误要报告交付未完成，稍后用相同 `TASK_ID` 重复查询原任务再下载，不重新生成。上游链接通常 24 小时有效，2.5 视频链接最多下载 100 次；查询原任务不保证延长上游文件期限，过期/清理后须核对可用归档，不能套用平台签名重签恢复。下载到本地后尽快转存。

返回的 `duration` 为整数秒约数（总帧数 / 24 向下取整）。不要改用 `https://platform.sgt.site/v1/videos/{id}` 或 `https://platform.sgt.site/v1/videos/{id}/content`，Seedance 任务只能通过本节的查询入口读取。

<a id="native-seedance-section-6"></a>

## 2.6 取消与删除

```bash
BASE_URL="https://platform.sgt.site/volcengine"
curl -X DELETE "$BASE_URL/api/v3/contents/generations/tasks/task_example" \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

- `queued`（排队中）的任务会被取消，状态变为 `cancelled`，冻结的预算随之释放。
- `running`（运行中）的任务不能取消或删除，返回 400 `invalid_task_status`。
- `succeeded`、`failed`、`expired` 的任务会被删除记录；删除已成功的任务不会退还生成费用。
- 删除完成后查询返回 404；已取消并释放的任务再次删除可能返回 409。
- 提交或结算尚未完成时可能返回 503，稍后重试；状态暂时无法确认时返回 409 `delete_reconciliation_required`。
- 样片被待提交、处理中或受理待核对的后续任务占用时，删除返回 409；不会通过删除样片撤销后续生成。
- 成功返回 HTTP 200，正文与官方一致（空 `Result` 对象）。

删除会改变已有任务状态和可读性，不是停止前端轮询的替代操作。

<a id="native-seedance-section-7"></a>

## 2.7 官方接口与输入限制

官方接口：`POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks`，查询和删除为同一路径下的 `GET`/`DELETE …/tasks/{id}`。平台 Base URL 已包含厂商前缀 `/volcengine`，请求体和响应体保持原生格式；火山方舟 SDK 的 `base_url` 设为本页 Base URL 加 `/api/v3`，即 `https://platform.sgt.site/volcengine/api/v3`。

**图片 `image_url`：**

| 项 | 要求 |
| --- | --- |
| 来源 | 公网 URL，或 `data:image/<格式>;base64,<数据>`（格式小写） |
| 格式 | jpeg、png、webp、bmp、tiff、gif；Seedance 2.0 及以上另支持 heic、heif |
| 宽高 | 宽、高均在 [300, 6000] px |
| 宽高比 | [0.4, 2.5] |
| 大小 | 单张小于 30 MB |
| 数量 | 首帧 1 张；首尾帧 2 张；多模态参考：Seedance 2.5 为 1–30 张，Seedance 2.0 系列为 1–9 张 |

**参考视频 `video_url`：**

| 项 | 要求 |
| --- | --- |
| 来源 | 公网 URL（不支持 Base64） |
| 格式 | mp4、mov；视频编码 H.264/AVC、H.265/HEVC，音频 AAC、MP3（mov 另支持 PCM） |
| 分辨率 | 480p、720p、1080p、4k |
| 宽高 | 宽、高均在 [300, 6000] px，总像素在 407696（614×664）到 8295044（3326×2494）之间 |
| 宽高比 | [0.4, 2.5] |
| 帧率 | [24, 60] FPS |
| 大小 | 单个不超过 200 MB |
| 时长与数量 | Seedance 2.5：单个 [2, 30] 秒（视频编辑任务为 [4, 30] 秒），最多 10 个，合计不超过 30 秒；Seedance 2.0 系列：单个 [2, 15] 秒，最多 3 个，合计不超过 15 秒 |

**参考音频 `audio_url`：**

| 项 | 要求 |
| --- | --- |
| 来源 | 公网 URL，或 `data:audio/<格式>;base64,<数据>` |
| 格式 | wav、mp3 |
| 大小 | 单个不超过 15 MB |
| 时长与数量 | Seedance 2.5：单段 [2, 30] 秒，最多 10 段，合计不超过 30 秒；Seedance 2.0 系列：单段 [2, 15] 秒，最多 3 段，合计不超过 15 秒 |
| 组合 | Seedance 2.5 可以只传音频；Seedance 2.0 系列必须同时带至少 1 张参考图或 1 个参考视频 |

**其他官方规则：**

- 整个请求体不超过 64 MB，大文件请用公网 URL，不要用 Base64。
- Seedance 2.5 / 2.0 系列不支持直接上传含真人人脸的参考图或视频；可使用本账号近 30 天内由这些模型生成的含人脸原始视频作为输入，或使用素材库中的虚拟人像、已授权真人素材。
- 提示词建议中文不超过 500 字、英文不超过 1000 词。
- 图生视频时若所选比例与图片不一致，模型会居中裁剪图片。
- 任务 ID 保存 7 天，结果视频和尾帧链接 24 小时内有效。

**输出分辨率与像素：**

| 分辨率 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 | 21:9 |
| --- | --- | --- | --- | --- | --- | --- |
| 480p（2.0 系列） | 864×496 | 752×560 | 640×640 | 560×752 | 496×864 | 992×432 |
| 480p（2.5） | 854×480 | 752×560 | 640×640 | 560×752 | 480×854 | 992×432 |
| 720p | 1280×720 | 1112×834 | 960×960 | 834×1112 | 720×1280 | 1470×630 |
| 1080p | 1920×1080 | 1664×1248 | 1440×1440 | 1248×1664 | 1080×1920 | 2206×946 |
| 4k（仅 2.0） | 3840×2160 | 3326×2494 | 2880×2880 | 2494×3326 | 2160×3840 | 4398×1886 |

Seedance 2.5 的 1080p 和 Seedance 2.0 的 4k 输出为 10bit、H.265/HEVC 编码，少数播放器可能无法播放。

<a id="native-seedance-h-829cfa88"></a>

## 2.8 样片与正式视频

只有 `doubao-seedance-2-5-260628` 支持此流程。两步都调用同一个提交接口，各自创建独立平台任务并分别计费；平台不会替调用方自动发起第二步。

<a id="native-seedance-h-40e19111"></a>

### 第一步：生成 480p 样片

```bash
BASE_URL="https://platform.sgt.site/volcengine"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"doubao-seedance-2-5-260628","content":[{"type":"text","text":"蓝色纸船在平静水面漂动，固定镜头"}],"draft":true,"resolution":"480p","duration":4,"ratio":"16:9","generate_audio":false}'
```

保存返回的 `id`，按单任务查询接口等待 `succeeded`，读取 `content.video_url` 预览。普通 480p 视频不会被当成样片。

<a id="native-seedance-h-c62c1286"></a>

### 第二步：确认后提交正式视频

将下例的 `task_sample` 替换为第一步返回的平台任务 ID：

```bash
BASE_URL="https://platform.sgt.site/volcengine"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"doubao-seedance-2-5-260628","content":[{"type":"draft_task","draft_task":{"id":"task_sample"}}],"resolution":"1080p","watermark":false,"return_last_frame":true}'
```

| 参数 | 正式视频规则 |
| --- | --- |
| `model` | 与样片相同 |
| `content` | 仅一项 `draft_task`，不能再带文本或素材 |
| `resolution` | 必须显式为 `1080p` |
| `draft` | 省略或 false |
| `duration/ratio/seed/generate_audio/omni_reference_task_type` | 从样片自动继承，禁止重复发送，即使值与样片相同 |
| `watermark/return_last_frame/output_format` 等可调整项 | 按该型号能力重新指定；省略时使用官方默认值，不沿用样片设置 |

源样片必须属于当前消费主体、企业和原生协议，生成成功，处于上游创建后的七天有效期内，且平台保有可靠的样片上下文。已删除、取消、失败、过期或受理待核对的任务不能作为源；平台固定原渠道、原上游身份和模型映射，条件变化会在新生成前拒绝。

如果样片最初引用了平台素材，正式提交还会重新检查原素材是否仍存在、当前是否有权使用、服务身份是否一致，并在本次生成期间占用这些素材。素材已删除、失效或不再授权时，在冻结费用和发送正式请求前拒绝；不要在正式请求里重新发送素材来绕过检查。样片成功不会延长原素材的保留期，七天是样片任务的引用期限，并非素材保留承诺。

官方说明正式生成继承输入素材，但没有保证删除原素材对象后仍可生成；平台因此采用上述保守校验。旧样片缺少可靠的素材来源记录时也会拒绝转换，不根据展示输入猜测。正式任务仍在运行或结果待核对时，删除相关平台素材会返回冲突；确认终态后不因历史样片引用永久阻止删除。

样片按 480p 价格结算，正式视频按这次提交时的 1080p 价格冻结并按真实用量结算。是否属于“含输入视频”的价格取决于样片最初的输入；样片视频本身不算新的参考视频。正式视频失败不会退还已完成样片的费用。第二步返回新的平台任务 ID，独立查询。

<a id="native-seedance-h-3fc9a343"></a>

## 2.9 列表查询

`GET /api/v3/contents/generations/tasks` 查询当前主体可见的原生视频任务。权限和时间范围先于分页执行，范围为上游创建时间 `[T-7天,T)`，T 为本次服务器 UTC 秒级时间。不会返回共享账号中的其他主体任务。

```bash
BASE_URL="https://platform.sgt.site/volcengine"
KEY="替换为你的完整虚拟密钥"
curl --get "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'filter.model=doubao-seedance-2-5-260628' \
  --data-urlencode 'filter.status=succeeded'
```

| 查询参数 | 默认与允许值 |
| --- | --- |
| `page_num` | 默认 1，范围 1–500 |
| `page_size` | 默认 20，范围 1–500 |
| `filter.model` | 可选平台完整模型 ID；平台在内部关联原上游型号或接入点 |
| `filter.status` | 可选 `queued/running/succeeded/failed/cancelled/expired` |
| `filter.service_tier` | 默认 default，可筛选 default/flex；不因此开放本期型号的 flex 提交 |
| `filter.task_ids` | 可重复传入平台任务 ID，例如 `filter.task_ids=task_a&filter.task_ids=task_b` |

HTTP 200 返回 `{"items":[...],"total":1}`；每个 `items` 元素与单任务查询使用相同的状态规则，并补入已保存的创建时间等字段，字段出现条件见“2.5 提交和查询响应”。无匹配时返回 `{"items":[],"total":0}`，显式任务 ID 也不能绕过七天窗口。列表读取不新增生成或计费。

<a id="native-seedance-h-70d03364"></a>

## 2.10 联网搜索与优先级

纯文本生成可在本次请求中附加：

```json
{"tools":[{"type":"web_search"}]}
```

这是请求体片段，应与 `model/content` 等字段一并发送。只接受一个 web_search 工具，不接受其他类型、重复工具或未声明的工具字段；含图片、音频、视频或 `draft_task` 的请求不能携带该工具配置。

只有平台已配置当前模型的有效搜索价格和预留估计时才会提交。生成 token 与搜索次数分别计量；最终读取 `usage.tool_usage.web_search`，明确的 0 表示没有搜索。缺失次数、异常类型或搜索费用超过本次独立预留时保留待核对，不按 0 或 1 猜测，也不自动重新生成。

样片请求如果符合纯文本条件并显式开启搜索，按样片本次请求独立计量。转正式视频时不复制源任务的搜索参数、次数或价格；如上游意外返回未定价的工具用量，正式任务保持账务待核对。

`priority` 影响同一 Endpoint 的排队顺序。平台共享 Endpoint 只允许省略或 `0`，非零值需要管理员事先核实企业独占的接入点及原上游身份，并明确允许的 0–9 范围。没有这项配置时返回 400，不会静默改成 0。

<a id="native-seedance-h-621b5927"></a>

## 2.11 回调

生成请求可提供 `callback_url`，默认使用平台允许访问的 HTTPS 地址。平台根据已经持久化的任务状态向该地址发送 POST，正文沿用单任务查询格式，使用平台任务 ID 和受控错误摘要。

接收端应根据平台事件 ID 去重。通知可能因查询周期或投递重试延迟，不承诺观察到每个中间状态；投递失败不会重新生成或修改已确认账单。通知附带 `X-Heighliner-Event-Id`、`X-Heighliner-Event-Sequence`、`X-Heighliner-Signature`，按[任务回调与验签](task-callbacks.md)校验，不携带上游账号凭据。