# 视频生成 API

视频生成采用异步任务模式：创建任务 → 轮询状态 → 取结果。视频与 3D 共用同一个任务接口，按 `model` 字段分流。

> 当前模型列表和模型广场暂无公开可发现的视频模型调用名。以下视频请求仅用于展示结构，不能直接执行；`<MODEL_CALL_NAME>` 必须替换为模型广场后续发布的真实调用名。

> 视频生成走自有接口 + API Key，不是火山 AK/SK 签名。火山兼容接口仅用于素材管理。

## 关键参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型调用名，必须从模型广场或模型列表获取 |
| `content` | array | 是 | 输入内容，支持 `text`、`image_url`、`video_url`、`audio_url` |
| `resolution` | string | 否 | 模型透传字段；常见值为 `480p` / `720p` / `1080p`，以模型详情为准 |
| `ratio` | string | 否 | 模型透传字段；常见值为 `16:9` / `9:16` / `4:3` / `3:4` / `1:1` / `21:9` |
| `duration` | integer | 否 | 模型透传字段；时长范围以模型详情为准 |
| `frames` | integer | 否 | 模型透传字段；是否可与 `duration` 互换以模型详情为准 |
| `generate_audio` | boolean | 否 | 模型透传字段；是否支持配音以模型详情为准 |
| `tools` | array | 否 | 模型透传字段；支持的工具以模型详情为准 |

**创建任务认证：** `Authorization: Bearer <API_KEY>` 或 `x-api-key: <API_KEY>`

**查询和取消任务认证：** `Authorization: Bearer <API_KEY>`

> `https://www.silvamux.com/api/v3` 即接入域名下的 `/api/v3`，对应路由 `/api/v3/contents/generations/tasks`。

## 文生视频

```bash
curl -X POST https://www.silvamux.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_CALL_NAME>",
    "content": [{"type": "text", "text": "一只金毛犬在海滩上奔跑"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'
```

## 图生视频

图生视频分首帧、首尾帧两种场景（互斥）。

### 首帧

```bash
curl -X POST https://www.silvamux.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_CALL_NAME>",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "text", "text": "镜头缓缓拉远"}
    ]
  }'
```

### 首尾帧

```bash
curl -X POST https://www.silvamux.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_CALL_NAME>",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"},
      {"type": "text", "text": "镜头从白天过渡到夜晚"}
    ]
  }'
```

## 多模态参考生视频

参考图片（1~9）+ 参考视频（0~3）+ 参考音频（0~3）+ 文本提示词（可选）生成视频，支持全新生成、编辑、延长。

```bash
curl -X POST https://www.silvamux.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_CALL_NAME>",
    "content": [
      {"type": "image_url", "image_url": {"url": "asset://AST-XXXX"}, "role": "reference_image"},
      {"type": "text", "text": "让画面中的角色跳舞"}
    ]
  }'
```

> 不可单独输入音频，应至少包含 1 个参考视频或图片。三种图生视频场景（首帧/首尾帧/多模态参考）互斥。

## content 字段

### 文本（text）

| 字段 | 必选 | 说明 |
| --- | --- | --- |
| `type` | 是 | `text` |
| `text` | 是 | 提示词，支持中英文。建议中文 ≤500 字，英文 ≤1000 词 |

### 图片（image_url）

| 字段 | 必选 | 说明 |
| --- | --- | --- |
| `type` | 是 | `image_url` |
| `image_url.url` | 是 | 图片 URL、Base64 编码（`data:image/png;base64,...`）或素材 ID（`asset://<ASSET_ID>`） |
| `role` | 条件 | `first_frame`、`last_frame`、`reference_image` |

图片要求：格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；宽高 300–6000px；单张 ≤30MB。

### 视频（video_url）

| 字段 | 必选 | 说明 |
| --- | --- | --- |
| `type` | 是 | `video_url` |
| `video_url.url` | 是 | 视频 URL 或素材 ID |
| `role` | 条件 | 当前仅支持 `reference_video` |

视频要求：格式 mp4/mov；分辨率 480p/720p/1080p；时长 ≤15s，最多 3 个参考视频，总时长 ≤15s；单个 ≤50MB；帧率 4–60fps。

### 音频（audio_url）

不可单独输入音频。

| 字段 | 必选 | 说明 |
| --- | --- | --- |
| `type` | 是 | `audio_url` |
| `audio_url.url` | 是 | 音频 URL、Base64 编码或素材 ID |
| `role` | 条件 | 当前仅支持 `reference_audio` |

音频要求：格式 wav/mp3；时长 ≤15s，最多 3 段，总时长 ≤15s；单个 ≤15MB。

## 响应

创建任务返回任务 ID：

```json
{
  "id": "VTK-01JXXXXXXXXXXXXXX",
  "model": "<MODEL_CALL_NAME>",
  "status": "queued",
  "created_at": "2026-03-31T12:00:00Z"
}
```

## 查询任务

```
GET /api/v3/contents/generations/tasks/:id
```

```bash
curl https://www.silvamux.com/api/v3/contents/generations/tasks/VTK-01JXXXXXXXXXXXXXX \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"
```

成功响应：

```json
{
  "id": "VTK-01JXXXXXXXXXXXXXX",
  "status": "succeed",
  "result": {"video_url": "https://..."}
}
```

任务状态：`queued`（排队）→ `running`（生成中）→ `succeed` / `failed` / `cancelled` / `expired`。

## 取消任务

```
DELETE /api/v3/contents/generations/tasks/:id
```

仅 `queued` 状态可取消。

## 生成样例

多模态参考生视频（背景图 + 妆造三视图 + 面部特写图 + 提示词）：

![](https://silvamux-docs.tingyutech.com/cases/1a.webp)

提示词：

> 背景参考图片 1，月白虚影闪过，公子（妆造参考图片 2；人物形象严格参考图片 3）旋身开合折扇，鎏金扇刃弹出，墨竹扇面翻飞，慢鼓重响 1 声；特写：折扇刃格挡反派长刀，扇骨与刀身相击，公子唇角勾轻佻笑意，眼神却冷冽，指腹轻转扇柄。慢镜：公子侧身贴地滑步，折扇刃贴反派腿侧划过，带起一道浅痕，锦袍下摆扫过地面，玉簪轻晃。快切：公子旋身抬手，折扇刃飞射而出，擦过反派脖颈，钉入身后木柱，反派僵立不敢动。反转：身后突然传来掌风，公子旋身接掌，指尖相触时借力后跳，折扇刃从木柱飞回手中，眼神警惕。慢镜高光：公子折扇半开，扇刃抵唇侧，抬眸望向身后，碎发被风吹起，眉梢微扬，带一丝桀骜。拉镜：公子立于庭院石台上，折扇轻摇，镜头拉远，庭院四角同时浮现戴面具的黑影（持弯刀，呈合围之势）。定格：公子折扇合起一半，扇刃露鎏金锋芒，抬步向前，画面压暗，只留他的侧影和扇刃光，音效骤停。音效：折扇开合脆响 + 刃风切割声 + 慢鼓卡点（偏沉稳）。

<video style="max-width: 480px; margin: 0 auto;" src="https://silvamux-docs.tingyutech.com/cases/1a-h265.mp4" controls></video>

## 可用模型

当前可在模型广场发现的 3D 样例模型：`doubao-seed3d-2.0`。视频模型暂无公开可发现的调用名。

> 完整模型清单见[模型广场](/models)。部分模型需要权限标志，由管理员配置。

## 计费

视频生成按模型与视频参数（分辨率、时长、是否配音）计费，当前单价请在[模型广场](/models)打开对应模型详情查看。

## 与火山官方接口的差异

SilvaMux 的 Seedance 接口与火山官方接口字段相似（同款模型），但：

- **鉴权**：用平台 API Key（`sk_live_`），不是火山 AK/SK。
- **Base URL**：`https://www.silvamux.com/api/v3`（平台域名），不是火山方舟域名。
- **model**：使用模型广场或模型列表展示的真实调用名，不是火山 endpoint ID。
- **任务查询**：通过轮询 `GET /api/v3/contents/generations/tasks/:id` 查询任务状态。