# 视频生成

> 统一异步视频提交：字段白名单、默认值与各模型示例。

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

| 方法 | 路径 |
| --- | --- |
| POST | `/apimart/v1/videos/generations` |

<a id="apimart-videos-section-1"></a>

## 4.1 参数白名单

共同字段为 `model/prompt/size/resolution`；每个模型系列只接受下面列出的追加字段。

| 系列 | 追加字段 |
| --- | --- |
| Seedance | `duration, aspect_ratio, seed, audio, generate_audio, return_last_frame, watermark, image_urls, image_with_roles, video_urls, audio_urls, first_frame_image, last_frame_image` |
| MiniMax H3 | `duration, aspect_ratio, watermark, image_urls, image_with_roles, video_urls, audio_urls, first_frame_image, last_frame_image` |
| 可灵 3.0 / Turbo | `duration, mode, aspect_ratio, audio, generate_audio, watermark, multi_shot, image_urls, first_frame_image, last_frame_image, video_urls`；部分字段仍受型号限制 |
| 可灵 Omni | 上一行全部字段，另有 `image_with_roles, video_list` |

通用类型：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，视频模型 |
| `prompt` | string | H3/可灵必填；Seedance 可由有效媒体提供输入，通常仍建议明确描述 |
| `duration` | integer | 不接受 `"5"` 这样的字符串 |
| `size / aspect_ratio` | string | 视频比例的两个名称；同时给出时必须完全一致 |
| `resolution` | string | 视频分辨率，见型号表 |
| `audio / generate_audio` | boolean | 音频开关的两个名称，仅支持的型号可用；同时给出须一致 |
| `watermark` | boolean | 水印 |
| `image_urls / video_urls / audio_urls` | string[] | 素材地址；具体语义依模型 |
| `first_frame_image / last_frame_image` | string | 首帧/尾帧地址 |
| `image_with_roles` | object[] | 元素仅允许 `url`、`role` |

**视频 size 表示比例**，如 `16:9`；不要套用图片像素 size，也不要把统一 Omni 入口支持的像素别名直接用于 APIMart。

`image_urls` 与非空 `image_with_roles` 不能混用；显式首尾帧不能与非空图片数组混用。可灵指定显式尾帧时必须有首帧。视频/音频素材使用 HTTP(S) URL；图片可使用受支持 Data URI。APIMart 不支持素材字段中的 `asset://`。

<a id="apimart-videos-section-2"></a>

## 4.2 模型默认值和范围

| 模型 | 默认值 | 支持范围 |
| --- | --- | --- |
| Seedance 2.0 | 5s、16:9、720p、有声 | 4–15s 或 -1；480p/720p/1080p/4k |
| Seedance 2.0 Fast / Mini | 5s、16:9、720p、有声 | 4–15s 或 -1；480p/720p |
| Seedance 2.5 | 5s、adaptive、720p、有声 | 4–30s 或 -1；480p/720p/1080p |
| MiniMax H3 | 5s、2K；纯文本 16:9 | 4–15s；768P/2K；图片/视频输入通常默认 adaptive |
| 可灵 3.0 | 5s、16:9、std/720p、无声、单镜头 | 3–15s；std/720p、pro/1080p、4k |
| 可灵 Turbo | 5s、16:9、720p | 3–15s；720p/1080p；不接受音频设置、尾帧和 4k |
| 可灵 Omni | 5s、16:9、720p；纯文本/图片默认无声、单镜头 | 3–15s；参考视频约束见 4.6 |

MiniMax 仅有音频参考时不会自动切换为 adaptive，需要时显式指定；纯文本不能使用 adaptive。以上为 APIMart 协议的默认值，与官方原生接口可能不同；Turbo 的音频不能通过本协议开关。

<a id="apimart-videos-section-3"></a>

## 4.3 Seedance 视频

文生视频：

```json
{
  "model": "seedance-2.0",
  "prompt": "镜头缓慢推进，清晨阳光照亮桌上的白色陶瓷杯",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false
}
```

首尾帧：

```json
{
  "model": "seedance-2.0",
  "prompt": "从第一张图片平滑过渡到最后一张图片",
  "first_frame_image": "https://media.example.com/first.png",
  "last_frame_image": "https://media.example.com/last.png",
  "duration": 5,
  "aspect_ratio": "adaptive",
  "resolution": "720p",
  "generate_audio": false,
  "return_last_frame": true
}
```

多模态参考：

```json
{
  "model": "seedance-2.5",
  "prompt": "参考图片1的角色和视频1的运镜，生成自然行走的片段",
  "image_with_roles": [
    {"url": "https://media.example.com/person.png", "role": "reference_image"}
  ],
  "video_urls": ["https://media.example.com/motion.mp4"],
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "generate_audio": false
}
```

Seedance 的 `image_urls` 始终映射为 reference_image，不自动作为首帧。`image_with_roles.role` 只接受 `first_frame/last_frame/reference_image`。video_urls/audio_urls 分别映射为 reference_video/reference_audio。

APIMart 不接受 Seedance 原生 `content`、`ratio`、`omni_reference_task_type`、`output_format`、`priority`、`tools` 等字段；需要这些能力时使用原生协议。-1 时长按模型上限冻结预算、按实际时长结算。图片、视频、音频的格式、尺寸、时长和数量要求与原生 Seedance 相同（例如图片宽高 [300, 6000] px、宽高比 [0.4, 2.5]、小于 30 MB；Seedance 2.0 系列最多 9 张图、3 个视频、3 段音频），详见原生协议 Seedance 章节。

<a id="apimart-videos-section-4"></a>

## 4.4 MiniMax H3 视频

```json
{
  "model": "MiniMax-H3",
  "prompt": "让参考图中的人物自然转头并微笑",
  "image_urls": ["https://media.example.com/person.png"],
  "duration": 5,
  "resolution": "2K",
  "aspect_ratio": "adaptive",
  "watermark": false
}
```

最多 9 张参考图、3 个参考视频、3 个参考音频；素材格式、尺寸、时长要求与原生 MiniMax H3 相同（图片 [256, 5760] px、≤30 MB，视频 ≤50 MB，音频 ≤15 MB，单段 2–15 秒且合计不超过 15 秒）。image_urls 始终为参考图；需要首尾帧时使用显式帧字段或 `image_with_roles`。role 与 Seedance 一致。首尾帧与参考模式不可混用。

watermark 转成原生 aigc_watermark。H3 不接受 `audio/generate_audio/seed/return_last_frame`；不要传入 false 试图绕过白名单。

<a id="apimart-videos-section-5"></a>

## 4.5 可灵 3.0 与 Turbo

```json
{
  "model": "kling-v3",
  "prompt": "镜头沿着海岸向灯塔移动，海浪轻轻拍打岸边",
  "duration": 5,
  "mode": "std",
  "aspect_ratio": "16:9",
  "audio": false,
  "multi_shot": false,
  "watermark": false
}
```

- mode 的 `std/pro/4k` 分别映射 `720p/1080p/4k`。同时提供 resolution 时必须匹配。
- 3.0 的 image_urls 传入一张为首帧，两张为首尾帧；超过两张会被拒绝。
- Turbo 仅支持首帧，不能设置 audio/generate_audio，也不接受尾帧和 4k。新请求省略 multi_shot。
- 普通 3.0/Turbo 不支持参考视频，即使 video_urls 是白名单字段，非空值仍会被拒绝。
- 除下节 Omni feature 模式外，APIMart 不支持 `multi_shot=true` 或自定义分镜。
- 图片需为 jpg/jpeg/png、不超过 50 MB、宽高不小于 300 px、宽高比 1:2.5–2.5:1，完整要求见原生协议可灵章节。

<a id="apimart-videos-section-6"></a>

## 4.6 可灵 Omni

模型使用 `kling-v3-omni`。支持文本、参考图片、首尾帧、视频编辑和特征参考。

图片参考：

```json
{
  "model": "kling-v3-omni",
  "prompt": "让 <<<image_1>>> 中的人物向镜头挥手",
  "image_urls": ["https://media.example.com/person.png"],
  "duration": 5,
  "mode": "std",
  "audio": false
}
```

视频编辑：

```json
{
  "model": "kling-v3-omni",
  "prompt": "将参考视频的场景改成暖色落日氛围",
  "duration": 5,
  "mode": "std",
  "video_list": [
    {
      "video_url": "https://media.example.com/reference.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}
```

首帧加特征参考：

```json
{
  "model": "kling-v3-omni",
  "prompt": "让 <<<image_1>>> 中的人物参考视频动作自然行走",
  "image_urls": ["https://media.example.com/person.png"],
  "video_list": [
    {
      "video_url": "https://media.example.com/motion.mp4",
      "refer_type": "feature",
      "keep_original_sound": "no"
    }
  ],
  "duration": 5,
  "mode": "std"
}
```

规则：

| 输入 | 映射与限制 |
| --- | --- |
| 无视频的 image_urls | refer_image，最多 7 张；默认单镜头，可显式 audio=true |
| video_list + refer_type=base | base_video；默认 base、默认 multi_shot=false；最多 4 张参考图；不能有首尾帧 |
| video_list + refer_type=feature | feature_video；multi_shot 默认 true；image_urls 最多一张并作为首帧 |
| video_urls | 旧写法，等同 feature 参考视频；最多一个；默认 multi_shot=true；图片数组仍为参考图，最多 4 张 |
| image_with_roles | role 为 `first_frame/last_frame/reference`；注意这里是 reference，不是 Seedance/H3 的 reference_image |

`video_list` 最多一个对象，严格只接受 `video_url/refer_type/keep_original_sound`：

- `refer_type` 只能为 base 或 feature，省略为 base。
- `keep_original_sound` 目前只支持 no，省略同 no；yes 返回 400。
- 非空 video_list 不能同时传 audio 或 generate_audio，**包括 false**。
- 非空 video_list 与非空 video_urls 互斥；对象中若以 `url` 替代 video_url 也会被拒绝。
- feature 要求 multi_shot=true，base 要求 false；显式传错不会被自动覆盖。
- 旧写法 video_urls 可以显式 audio=false，但不接受生成音频。
- 图片角色数组不能与 image_urls 或显式首尾帧混用；不能单独传尾帧或重复传首尾帧。
- `<<<image_N>>>` 转为原生 `@image_N`，N 从 1 开始且不得越界。image_urls 非空且提示词未引用时，会自动引用第一张；显式角色数组不会自动改写未引用的提示词。

不支持 APIMart 元素库、动作控制、自定义分镜等额外能力。参考视频需为 mp4/mov、不超过 200 MB、3–15.5 秒、宽高 700–4553 px；输出时长与比例可能受素材影响，720p 不保证固定为 1280×720。带参考视频时按 16 秒冻结预算，完成后按实际时长结算。