# 分组 5 · Seedance 2.5 API

更新：2026-10-28。适用于奶龙站分组 5 的 **`seedance-2.5`**。调用流程是 **提交 JSON → 保存任务 ID → 查询进度 → 下载视频**。

> **遇到 `unsupported field images`：** 把参考图字段改为 `reference_images`，按下文格式传值，并删除原来的 `images`。纯文生视频不要发送图片字段，空的 `images: []` 也会报错。创建分组 5 的 Key 只解决权限与路由，不会替软件转换参数。

## 接口与鉴权 {#endpoints}

| 项目 | 配置 |
|---|---|
| 服务根地址 | `https://api.nailongapi.cc` |
| 模型 ID | `seedance-2.5`，注意中间的连字符 |
| API Key | 使用有分组 5 和该模型权限的奶龙站 Key；推荐先用分组 5 专用 Key 接入 |
| 鉴权头 | `Authorization: Bearer sk-YOUR_NAILONG_API_KEY` |
| 提交格式 | `Content-Type: application/json`；本模型不接受 multipart 文件表单 |
| 创建任务 | `POST /v1/videos` |
| 查询任务 | `GET /v1/videos/{id}` |
| 下载结果 | `GET /v1/videos/{id}/content`，仍需同一账户下有权限的 Key |

混合分组 Key 也必须具备对应权限和正确路由。请求体不需要添加 `group` 字段。API 请求发往上面的服务根地址，不发往文档站。

## 先跑通一条文生视频请求 {#quickstart}

将以下内容保存为 `video-request.json`：

```json
{
  "model": "seedance-2.5",
  "prompt": "海边日落，镜头缓慢向前推进，海浪轻轻拍打沙滩",
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "enable_audio": true
}
```

在自己的服务端环境设置 `NAILONG_API_KEY` 后执行下面的 Bash 命令。Windows PowerShell 使用 `curl.exe` 和 `$env:NAILONG_API_KEY`，不要直接照搬 Bash 的换行符。

```bash
curl --fail-with-body 'https://api.nailongapi.cc/v1/videos' \
  -H "Authorization: Bearer ${NAILONG_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @video-request.json
```

**执行会创建收费任务。** 当前价格以本站模型详情和 Key 所属分组为准。提交后先保存回执中的 `id`，不要为了等待视频而重复执行 POST。

## 请求参数 {#parameters}

| 参数 | 类型 | 必填 / 默认 | 说明 |
|---|---|---|---|
| `model` | string | 必填 | 精确填写 `seedance-2.5` |
| `prompt` | string | 文生视频必填 | 有图片、视频参考或首尾帧时可省略；建议写明生成要求。仅音频参考不能替代提示词 |
| `seconds` | integer | 必填 | **4–30**，推荐用整数；兼容别名 `duration`，不要同时发送冲突值 |
| `resolution` | string | 与 `aspect_ratio` 成对填写 | `480p`、`720p`、`1080p` |
| `aspect_ratio` | string | 与 `resolution` 成对填写 | `16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`21:9`、`adaptive` |
| `size` | string | 替代上述两个字段 | 使用下方尺寸表的精确值；推荐只选一种尺寸表达，避免冲突 |
| `enable_audio` | boolean | 可选，默认 `true` | 是否生成声音；传 `true` / `false`，不要传字符串 |
| `reference_images` | array | 可选 | 最多 **30 张**；元素为图片 URL 字符串，或 `{ "image_url": "…" }` |
| `reference_videos` | array | 可选 | 最多 **10 段**；元素为 `{ "video_url": "…" }`，不能直接用 URL 字符串数组 |
| `reference_audios` | array | 可选 | 最多 **10 段**；元素为 `{ "audio_url": "…" }`，不能直接用 URL 字符串数组 |
| `first_frame` | string / object | 可选 | 首帧图片，格式与单个参考图片元素一致；兼容 `input_reference` 或 `image`，三者只选一个 |
| `last_frame` | string / object | 可选 | 尾帧图片，格式与单个参考图片元素一致；可用组合受模型限制，见下文 |
| `metadata` | object | 可选 | 仅接受 `client_request_id`；用于业务关联，不应把它当作本站已保证的重复提交保护 |
| `extra_parameters` | object | 可选 | 仅兼容 `enable_audio`；建议直接使用顶层参数，不重复传 |

`metadata.client_request_id` 是不超过 200 字符的字符串，不含斜杠、反斜杠、换行或空字符。客户端仍应保存本站返回的任务 `id`。

**不接受未列出的字段**，例如 `images`、`videos`、`audios`、`image_urls`、`ratio`、`n`。不需要的字段应省略，不要把其他模型的整套参数原样带过来。参数通过本站校验不代表所有素材组合一定能通过生成服务的审核。

### 尺寸对应表

推荐发送 `resolution` + `aspect_ratio`；如果软件只能配置 `size`，使用此表。

| 比例 | 480p 的 size | 720p 的 size | 1080p 的 size |
|---|---|---|---|
| `16:9` | `854x480` | `1280x720` | `1920x1080` |
| `9:16` | `480x854` | `720x1280` | `1080x1920` |
| `4:3` | `640x480` | `960x720` | `1440x1080` |
| `3:4` | `480x640` | `720x960` | `1080x1440` |
| `1:1` | `480x480` | `720x720` | `1080x1080` |
| `21:9` | `1120x480` | `1680x720` | `2520x1080` |
| `adaptive` | `adaptive-480p` | `adaptive-720p` | `adaptive-1080p` |

## 参考图片完整示例 {#reference-images}

把下面 JSON 保存为同一个 `video-request.json`，使用上方 POST 命令提交。示例素材域名是占位地址，**必须替换成你的真实、无需登录即可下载的图片链接**。

```json
{
  "model": "seedance-2.5",
  "prompt": "以参考图片中的场景为基础，镜头缓慢向前推进",
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "enable_audio": true,
  "reference_images": [
    {"image_url": "https://your-public-relay.example/media/reference.png"}
  ]
}
```

若软件原来的 `images` 是 **URL 字符串数组**，可以转换成 `reference_images` 字符串数组；若元素是其他对象，必须转换成表中支持的对象格式，不能只改字段名。

## 首帧与多种参考素材 {#reference-media}

首帧引导生成示例：

```json
{
  "model": "seedance-2.5",
  "prompt": "从首帧画面开始，镜头缓慢拉远",
  "seconds": 5,
  "size": "1280x720",
  "enable_audio": false,
  "first_frame": {
    "image_url": "https://your-public-relay.example/media/first-frame.png"
  }
}
```

使用尾帧时可传 `last_frame`。**字段存在不代表首帧、尾帧、普通参考图可任意混用**：先单独选择参考模式；若返回 `reference_mode_conflict` 或 `last_frame_conflict`，按提示移除冲突素材，不要反复原样提交。

视频及音频参考示例（替换两处素材链接）：

```json
{
  "model": "seedance-2.5",
  "prompt": "生成一段新视频，参考视频中的镜头运动和音频节奏",
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "enable_audio": true,
  "reference_videos": [
    {"video_url": "https://your-public-relay.example/media/motion.mp4"}
  ],
  "reference_audios": [
    {"audio_url": "https://your-public-relay.example/media/music.mp3"}
  ]
}
```

素材 URL 应返回媒体文件本身，不能是网盘分享页、网页或需要 Cookie 的地址。内联素材也可以放入对应的 `image_url` / `video_url` / `audio_url`：图片支持 PNG/JPEG/GIF Data URL，视频支持 MP4，音频支持 MP3/WAV；单份内联素材解码后最多 32 MiB，总 JSON 最多 64 MiB（包含 Base64 膨胀）。较大的素材建议使用公网 URL，网络入口可能有更早的大小限制。

高级场景可将素材 URL 对象替换为 `asset_id` 对象，但只能使用通过受支持上传流程获得的有效 ID；本页不提供奶龙站素材上传接口，也不要把本地文件名当作 asset ID。一个对象内 URL 与 `asset_id` 必须二选一。

生成阶段还可能检查图片尺寸、视频时长、音频总时长、内容及版权等。收到具体素材错误后应调整素材；数量上限不代表每种组合都能生成。

## 创建回执、查询与下载 {#task-flow}

创建回执示意，任务 ID 和时间仅用于展示结构：

```json
{
  "id": "task_example",
  "object": "video",
  "model": "seedance-2.5",
  "status": "queued",
  "created_at": 1700000000,
  "progress": 0
}
```

使用 **本站返回的 `id`** 查询，不要改为业务请求号或其他平台的任务号。下面命令中的 `task_example` 必须替换。

```bash
curl --fail-with-body 'https://api.nailongapi.cc/v1/videos/task_example' \
  -H "Authorization: Bearer ${NAILONG_API_KEY}"
```

| `status` | 含义 | 客户端行为 |
|---|---|---|
| `queued` | 已接纳 / 排队 | 保存 ID，继续查询 |
| `in_progress` | 生成中或结果仍在确认 | 每 10–30 秒查询原任务 |
| `completed` | 生成完成 | 使用内容接口下载 |
| `failed` | 任务已失败 | 读取 `error.code` 和 `error.message`，停止查询 |
| `unknown` / 其他值 | 暂不能识别 | 保留 ID，稍后查询或联系管理员 |

查询可能附带 `seconds`、`size`、`enable_audio`、`provider_status`、`diagnostic`、`file_status` 等字段；客户端不要假定每次都会返回。若 `provider_status` 表示 `submission_unknown` / `needs_review`，或诊断提示提交结果待确认，保留原任务，不重新生成。

`completed` 响应**不保证包含视频直链**。下载时仍使用鉴权头：

```bash
curl --fail-with-body 'https://api.nailongapi.cc/v1/videos/task_example/content' \
  -H "Authorization: Bearer ${NAILONG_API_KEY}" \
  --output video.mp4
```

先检查 HTTP 状态及响应类型再把文件当作视频处理。下载暂不可用时重新查询原任务，不重新 POST 生成。下载完成后及时保存到自己的存储；返回 `file_status: "deleted"` 或 `artifact_deleted` 时，不应继续假设原文件可下载。

任务排队和生成可能需要较长时间。当前后台任务总时限为 24 小时，客户端一次 HTTP 超时或关闭页面不会取消原任务。提交超时、断网或成功响应没有 ID 时，请保存请求时间和错误中的 request id 联系管理员核查，避免重复提交。

## 常见错误与处理 {#errors}

| 报错 / 现象 | 含义 | 处理 |
|---|---|---|
| `video request: unsupported field images` | 请求包含不支持的顶层字段 | 参考图改用 `reference_images` 并删除 `images`；纯文生视频直接删除图片字段 |
| `unsupported field videos` / `audios` | 使用了其他适配器的字段 | 改成 `reference_videos` / `reference_audios` 的对象数组 |
| `seconds must be an integer from 4 to 30` | 时长缺失或超出范围 | 明确传入 4–30 的整数 |
| `resolution and aspect_ratio must be supplied together` | 只传了清晰度或比例 | 成对填写，或单独使用受支持的 `size` |
| `size must match resolution and aspect_ratio` | 尺寸表达冲突 | 保留一种表达，或按尺寸表保持完全一致 |
| `Use JSON /v1/videos` | 使用了 multipart 或不支持的提交方式 | 使用 JSON 和 `Content-Type: application/json` |
| `reference_access_denied` / `reference_not_found` | 素材无法公开读取或已经失效 | 更换真实、可直接下载的媒体 URL |
| `reference_mode_conflict` / `last_frame_conflict` | 参考素材模式冲突 | 按提示选择一种参考方式 |
| `submission_pending` | 是否受理或结果仍在核查 | 有 ID 时继续查询，无 ID 时联系管理员，不自动重提 |
| `artifact_not_ready` / `artifact_unavailable` | 视频文件暂未就绪或不可下载 | 查询原任务或联系管理员，不再次生成 |

**“使用 JSON”只说明传输格式，还必须使用本页定义的字段和数据结构。** 分组 5 的参数与其他视频模型不同，通用 Skill 或其他分组的示例不能直接套用。

本文按已接入的 Seedance 2.5 请求校验与响应协议整理。示例经过本地协议校验；这不代表对所有参考素材组合执行过付费生成，实际效果、审核及可用性以当前服务结果为准。