# ByteSOTA AI Gateway API 接入指南
**一键发送给Agent自动接入：**
将本 Markdown 接入指南直接交给 Agent，即可按文中协议接入。若阅读的是飞书版本，可通过右上角菜单下载为 Markdown；无需同时发送内部架构或运营文档。
统一接入视频生成、再生成与提示词增强：选择型号与SKU规格，提交任务，查询结果，再下载保存。
**阅读导航**：模型清单 · 通用规则 · 快速入门 · 分模型接入 · 任务与文件 · 报错速查 · 余额与计费 · 网页控制台 · 低成本测试
# 文档版本信息
| **项目** | **内容** |
| ------------ | ----------------------------------------------------------------- |
| 文档版本 | 1.0.4 |
| 更新时间 | 2026-10-31（北京时间） |
| 适用API版本 | `/v1` |
| 收录范围 | 8个调用型号；型号能力与计量项目见下文，实时售价另在公开价格页展示 |
| 模型数量增减 | 支持8个调用型号 |
| 本次主要更新 | 统一 ByteSOTA API、控制台与结果链接域名；保留既有接入协议 |
| 其他备注 | 本指南不维护售价副本；查看控制台公开价格，缺价不表示免费 |
# 支持模型清单
本版覆盖8个调用型号。下表是能力与计量概览，不是实时售价目录。SKU按规格或计量项区分，`model`是接口调用名称；同一调用名称可对应多个SKU。共用接入规则的SKU合并列出，特殊条件单独说明。
实时价格可在控制台登录区下方无需登录查看。输入计量项随生成任务处理，不单独提交；是否收费及包含数量以有效报价为准。下表时长为输出时长，素材限制见对应型号。
| **模型厂商** | **模型名称** | **模型SKU** | **调用名称** | **一句话介绍** | **计价方式** | **支持输入** | **支持时长** | **输出结果** |
| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------- | ------------------ | -------------------------------------------------- | ----------------------------------- | --------------------------- |
| MiniMax | MiniMax H3 | - MiniMax\-H3 768P
- MiniMax\-H3 2K | `minimax-h3` | 文字、首尾帧与参考素材视频创作，支持768P和2K。 | 时长（1s） | 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 4～15整数秒 | 视频 |
| MiniMax | MiniMax H3 Max | - MiniMax H3\-Max 480P
- MiniMax H3\-Max 768P | `minimax-h3-max` | H3系列独立视频型号，提供480P至1080P规格。 | 时长（1s） | 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 5～15整数秒 | 视频 |
| MiniMax | MiniMax H3 Max | MiniMax H3\-Max 1080P | `minimax-h3-max` | H3系列独立视频型号，提供480P至1080P规格。 | 时长（1s） | 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 5～15整数秒 | 视频 |
| MiniMax | MiniMax H3 再生成 | MiniMax\-H3\-Regeneration 768P→2K 视频再生成 | `minimax-h3-regeneration` | 复用本人成功的H3 768P任务，再生成2K视频。 | 时长（1s） | H3源视频 | 继承源任务（4～15秒） | 2K视频 |
| MiniMax | MiniMax H3 | MiniMax\-H3 音频输入 | `minimax-h3` | 同一任务的输入计量项。 | 免费（不单独计费） | 参考音频 | 4～15整数秒 | 视频 |
| MiniMax | MiniMax H3 | MiniMax\-H3 input image 参考图片 | `minimax-h3` | 同一任务的输入计量项。 | 图片（1张） | 首尾帧图片 / 参考图片 | 4～15整数秒 | 视频 |
| MiniMax | MiniMax H3 | - MiniMax\-H3 768P input 参考视频
- MiniMax\-H3 2K input 参考视频 | `minimax-h3` | 同一任务的输入计量项。 | 时长（1s） | 参考视频 | 4～15整数秒 | 视频 |
| MiniMax | MiniMax H3 Max | MiniMax H3\-Max 音频输入 | `minimax-h3-max` | 同一任务的输入计量项。 | 免费（不单独计费） | 参考音频 | 5～15整数秒 | 视频 |
| MiniMax | MiniMax H3 Max | MiniMax H3\-Max input image 参考图片 | `minimax-h3-max` | 同一任务的输入计量项。 | 图片（1张） | 首尾帧图片 / 参考图片 | 5～15整数秒 | 视频 |
| MiniMax | MiniMax H3 Max | - MiniMax H3\-Max 480P input 参考视频
- MiniMax H3\-Max 768P input 参考视频
- MiniMax H3\-Max 1080P input 参考视频 | `minimax-h3-max` | 同一任务的输入计量项。 | 时长（1s） | 参考视频 | 5～15整数秒 | 视频 |
| MiniMax | MiniMax H3 再生成 | MiniMax\-H3\-Regeneration 768P→2K 音频输入 | `minimax-h3-regeneration` | 同一任务的输入计量项。 | 免费（不单独计费） | 源任务音频 | 继承源任务（4～15秒） | 2K视频 |
| MiniMax | MiniMax H3 再生成 | MiniMax\-H3\-Regeneration 768P→2K input image 参考图片 | `minimax-h3-regeneration` | 同一任务的输入计量项。 | 图片（1张） | 源任务图片 | 继承源任务（4～15秒） | 2K视频 |
| MiniMax | MiniMax H3 再生成 | MiniMax\-H3\-Regeneration 768P→2K input 参考视频 | `minimax-h3-regeneration` | 同一任务的输入计量项。 | 参考输入时长（1s） | 源任务的额外参考视频，不含原成片 | 继承源任务（4～15秒） | 2K视频 |
| MiniMax | MiniMax H3 Context IR | - MiniMax\-H3\-Context\-IR\-输入
- MiniMax\-H3\-Context\-IR\-输出 | `minimax-h3-context-ir` | 结合想法与素材增强提示词，返回可继续创作的文本。 | Token（1M）
| 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 目标视频节奏4～15秒；本次不输出视频 | 增强提示词文本 |
| 字节跳动Seedance | Seedance 2\.5 | Seedance\-2\.5 480P/720P input（参考视频\+生成视频=总时长） | `seedance-2.5` | 覆盖生成、编辑与延长，支持声音和可选尾帧输出。 | Token（1M）
| 参考视频 / 参考图片 / 参考音频 | 4～30整数秒或自动时长\-1 | MP4 / MOV视频，可选尾帧图片 |
| 字节跳动Seedance | Seedance 2\.5 | Seedance\-2\.5 480P/720P | `seedance-2.5` | 覆盖生成、编辑与延长，支持声音和可选尾帧输出。 | Token（1M）
| 文本 / 首尾帧图片 / 参考图片 / 参考音频 | 4～30整数秒或自动时长\-1 | MP4 / MOV视频，可选尾帧图片 |
| 字节跳动Seedance | Seedance 2\.5 | Seedance\-2\.5 1080P input（参考视频\+生成视频=总时长） | `seedance-2.5`
| 覆盖生成、编辑与延长，支持声音和可选尾帧输出。 | Token（1M）
| 参考视频 / 参考图片 / 参考音频 | 4～30整数秒或自动时长\-1 | MP4 / MOV视频，可选尾帧图片 |
| 字节跳动Seedance | Seedance 2\.5 | Seedance\-2\.5 1080P | `seedance-2.5` | 覆盖生成、编辑与延长，支持声音和可选尾帧输出。 | Token（1M）
| 文本 / 首尾帧图片 / 参考图片 / 参考音频 | 4～30整数秒或自动时长\-1 | MP4 / MOV视频，可选尾帧图片 |
| 生数科技 | Vidu Q4 Preview | - Vidu Q4 Preview 540P
- Vidu Q4 Preview 720P
- Vidu Q4 Preview 1080P
- Vidu Q4 Preview 2K
- Vidu Q4 Preview 4K | `vidu-q4-preview` | 基于图片创作视频，最高支持4K规格。 | 时长（1s） | 首帧图片 / 参考图片 / 参考音频 | 3～16整数秒 | 视频 |
| 阿里巴巴 | Wan 3\.0 | - 480P
- 720P
- 1080P | `wan-3.0` | 覆盖文字、首尾帧及多类参考素材，支持2～30秒视频。 | 时长（1s） | 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 2～30整数秒或自动时长\-1 | 视频 |
| 阿里巴巴 | Wan 3\.0 Prime | - 480P
- 720P
- 1080P | `wan-3.0-prime` | Wan系列Prime独立型号，使用独立权限和价格。 | 时长（1s） | 文本 / 首尾帧图片 / 参考图片 / 参考视频 / 参考音频 | 2～30整数秒或自动时长\-1 | 视频 |
SKU名称沿用来源表，具体计量以本段与有效报价为准，参数按字段表传递。H3/H3再生成图片前5张、H3-Max前2张免费，超出按张计费；这三类参考音频免费。IR的素材计入输入Token，不另按张或秒收费。Vidu图片和音频不另加费；Wan图片和音频不另加费，有参考视频时按可信输入秒数加输出秒数、以所选分辨率相同秒价计费。再生成仅重新计入原任务的额外参考输入，不把原成片再当参考视频收费。Seedance“含参考视频”档按最终 `completion_tokens`计量，不将秒数当作Token。Wan的480P／720P／1080P SKU需结合标准或Prime型号识别。
# 通用接入规则
## 接口地址与一览
接口根地址：`https://bytesota-api.businessmodelcraft.com`。下表路径均拼接在该地址之后。
主结果及附加文件使用接口返回的完整 URL，保留全部签名参数，不自行改写域名。
| **方法** | **路径** | **功能** | **认证与要求** |
| ---------- | ------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------ |
| POST | `/v1/videos/generations` | 提交视频生成、再生成或提示词增强任务 | Bearer Key；JSON；幂等键 |
| GET | `/v1/tasks/{id}` | 查询本人任务、结果、用量和费用状态 | Bearer Key |
| GET / HEAD | `/v1/tasks/{id}/content` | 下载、播放或探测主视频 | Bearer Key或有效签名链接 |
| GET / HEAD | `/v1/tasks/{id}/artifacts/{artifact_id}/content` | 获取尾帧等附加文件 | Bearer Key或对应文件的有效签名链接 |
| GET | `/v1/models` | 查询模型能力、当前默认参数、启用状态与本人权限 | Bearer Key |
| POST | `/v1/uploads/images` | 上传本地图片，取得本人素材引用 | Bearer Key；multipart/form\-data；唯一file字段 |
| POST | `/v1/uploads/videos` | 上传本地MP4，取得本人视频素材引用 | Bearer Key；multipart/form-data；唯一file字段 |
| GET | `/v1/media/usage` | 查询本人图片和视频容量占用 | Bearer Key |
| DELETE | `/v1/media/{media_id}` | 提前清理本人R2视频；任务保护期间拒绝 | Bearer Key |
| GET | `/v1/media/{media_id}` | 查询本人上传素材与新任务可用期限 | Bearer Key |
| GET / HEAD | `/v1/media/{media_id}/content` | 平台视频素材签名读取；通常由供应商拉取 | 仅有效平台签名，Bearer不能替代签名；不公开对象键 |
| GET | `/health` | 服务存活检查 | 无需认证；不代表模型生成能力可用 |
所有型号共用提交接口，通过 `model`区分；Context IR文本增强也使用该接口。
`enabled`表示型号启用，`allowed`表示本人权限；价格与余额仍需就绪。
## 请求要求
| **项目** | **要求** |
| ---------- | -------------------------------------------------------------------------------- |
| 认证 | `Authorization: Bearer YOUR_PLATFORM_API_KEY`；Key保存在客户服务端 |
| 生成请求 | `Content-Type: application/json`；JSON对象，最大64KiB |
| 幂等键 | 视频生成POST必须携带 `Idempotency-Key`，1～128个可见ASCII字符，不含逗号 |
| 类型与字段 | 使用真实JSON类型；不接受未知字段、`null`或错误类型；不用的字段省略 |
| 默认规格 | 字段表列基准默认值，当前值见 `/v1/models`；建议显式传时长、分辨率和画幅 |
| 提示词 | 去首尾空白后按Unicode码点计数；超长拒绝，不截断 |
| 模式 | 按明确素材用途确定；编辑／延长用型号专用字段；不接受 `mode` 或 `generation_type` |
| 浏览器接入 | 通过客户服务端调用，平台不开放任意网站跨域请求 |
支持声音开关的型号统一使用`generate_audio`（boolean），不接受`audio`别名；参考音频使用`audio_urls`，与输出声音开关是不同功能。型号不支持的字段仍明确拒绝。
## 素材准备
| **项目** | **要求** |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| 地址 | 外部素材用准入域名下的稳定HTTPS地址；图片和视频也可使用本人上传的media://引用，期限须覆盖排队与生成 |
| URL限制 | 不接受内网、IP、额外端口、账号密码、片段、重定向或供应商私域引用 |
| 图片 | 逐型号检查格式、大小、尺寸、比例与数量；HEIC／HEIF／TIFF本版不接受 |
| 视频／音频 | MP4／MOV需可解析H264／H265视频轨；音频使用PCM WAV或含Xing/Info的MP3，按型号限制 |
| 校验失败 | 实际元数据无法读取返回 `media_metadata_unavailable`；文件后缀或自报时长不能替代校验 |
| 上传方式 | 生成接口不接受本机路径、Base64、asset://或文件正文；本地图片或视频先上传，生成时填写返回的media://引用 |
已提供本地图片与视频上传接口；视频使用`POST /v1/uploads/videos`，将返回的`media://`引用填写到`video_urls`，详见文末“本地视频临时上传”。音频本地上传暂未提供，`audio_urls`仍需准入域名下可稳定读取的HTTPS地址。
首帧用`first_frame_image`，尾帧用`last_frame_image`；参考图用`image_urls`，所有型号都按参考图处理，不按图片张数猜测用途。复杂图片输入可用`image_with_roles`明确角色，但不重复指定同一首帧或尾帧。首帧约束开始画面，尾帧约束结束画面，参考素材指导创作；两类模式不能混用。具体限制与选用条件集中在型号字段表中。1MiB=1,048,576字节。
## 上传本地图片
没有可用HTTPS图片地址时，先上传一次，再把返回的`reference`填写到`first_frame_image`、`last_frame_image`、`image_urls`或角色数组的url中。无需自行存储或重新上传；素材仅能由本人使用，后续生成仍须满足所选型号的图片规格。
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/uploads/images' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--form 'file=@first-frame.png'
```
使用标准multipart/form\-data、唯一file文件字段，PNG/JPEG/WebP且不超过20MiB；让curl/FormData自动设置boundary，不另传额外表单字段。成功HTTP 201；上传接口不提供幂等去重承诺。
| **字段** | **含义** |
| ------------------------------------------------- | --------------------------------------------------------- |
| media\_id / state | 本人素材编号及状态；ready才表示上传确认成功 |
| reference | 可填写到生成图片字段的media://med\_\*引用；不可用时为null |
| metadata | 已确认的图片格式、大小、宽高等元数据；未知为null |
| expires\_at | 素材到期时间，UTC ISO 8601；不承诺永久保存 |
| new\_task\_usable\_until / usable\_for\_new\_task | 最晚新任务使用时间及当前是否可用，包含排队和读取时间预留 |
用`GET /v1/media/{media_id}`查询本人素材。state=unknown表示上传结果待核实，不自动重复上传；该引用不能用于生成。上传不是视频采购，上传状态与生成任务状态分别处理。
图片存储服务明确拒绝（含HTTP 402）返回`state=failed`；401/403/402分别映射HTTP 503与`upstream_authentication_error`／`upstream_permission_error`／`upstream_insufficient_balance`，请凭request_id联系维护者核查服务身份、权限或支付条件，无需因此更换平台Key或充值，停止连续重试。发送后结果未知返回`media_upload_unknown`，HTTP按原因区分502/503/504，可选cause；保留素材编号先查询，不连续重传。`media_capacity_exceeded`表示网关本地素材数量／字节配额已满，不代表供应商存储已满；这类配额不会每分钟重置，应联系维护者或等待素材到期，不连续重传。`media_upload_busy`表示平台当前已有上传进行中，返回HTTP 503及`Retry-After: 5`，待候后再试。供应商明确限频返回`upstream_upload_busy`及`Retry-After: 60`。已知Content-Length的multipart按整包长度与20MiB较小值预占，输入验证后缩减至实际文件字节；没有长度时仍按20MiB保守预占。
## 幂等与网络重试
幂等键标识业务动作，用于避免网络重试造成重复任务与重复费用。
| **场景** | **正确处理** | **结果** |
| -------------------------------- | ---------------------------------- | ---------------------------------------- |
| 首次提交业务动作 | 使用新幂等键 | 接收后获得新任务编号 |
| 提交超时、断连或未收到响应 | 用原幂等键与原参数重试 | 找回同一任务，不重复预留或生成 |
| 同一键、相同规范化参数 | 保持原请求 | 返回同一任务，沿用原价格版本 |
| 同一键、参数发生变化 | 恢复原参数；若确为新动作，使用新键 | 参数变化返回 `409 idempotency_conflict` |
| 查询或下载失败 | 重试原GET / HEAD | 不创建生成任务 |
| 已接收任务明确失败，需要重新创作 | 排查原因后，用新幂等键提交新动作 | 原键仍返回原失败任务，新键可能产生新费用 |
| `submission_unknown` | 保存任务编号，联系支持核实 | 停止自动重试生成，不使用新键重复提交 |
已存在任务重放可能返回HTTP `200`；仍在平台等位时可能返回 `202`。本版幂等记录不自动过期；重放不延长排队期限。
可选字段省略时会使用当前默认值，因此网络重试应保持原参数与规格。首次请求建议显式填写影响结果的参数。
# 快速入门
先向服务方获取API Key，确认模型权限、价格与可用余额。以下以H3生成5秒视频为例，依次提交、查询、下载。
## 第一步：提交任务
替换 `YOUR_PLATFORM_API_KEY`后，在终端执行以下完整请求：
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-quickstart-h3-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "日光照亮花园小径，一只小猫缓慢向前走，镜头以低机位平稳跟随。",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
```
任务已接收且同步阶段未确认失败时返回HTTP `202`，保存 `id`。响应带 `Location`查询路径与 `Retry-After`建议等待秒数。同步拒绝或提交结果未知返回对应4xx/5xx；如果已建立任务，错误响应仍带完整任务对象和 `id`，应保存编号并查询原任务。生成是否完成需查询 `status`。
## 第二步：查询进度与结果
将路径中的任务编号替换为第一步返回的 `id`：
```Bash
curl 'https://bytesota-api.businessmodelcraft.com/v1/tasks/vid_ABCDEFGHIJKLMNOP' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY'
```
按响应的 `next_poll_after_seconds` 等待后再查：大于0时至少等待对应秒数，等于0时停止自动轮询。平台会自动推进任务，无需重复提交。HTTP `200`仅表示查询成功；生成是否成功，请检查 `status`。
### 通用响应字段
提交和查询成功时，各型号共用同一任务对象。输入方式不改变视频结果结构；生成成功后按 `result.type`读取视频或文本，有附加文件时遍历 `result.artifacts`。HTTP请求被拒绝时返回错误对象，见报错速查。
基础调用保存 `id`，按 `status`和 `next_poll_after_seconds`查询，成功后读取 `result`。可选字段仅在有内容时返回；`result.artifacts`只列附加文件。
| 字段 | 类型 | 说明 |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | 平台任务编号；查询和文件读取使用此值 |
| `model` | string | 本任务调用的型号 |
| `operation` | string | `video.generate`、`video.regenerate`或`text.enhance` |
| `status` | string | 生成状态，详见任务状态 |
| `result` | object或null | 成功时为视频或文本结果；暂无结果为 `null` |
| `usage` | object（可选） | 已知计量才返回；省略表示未知，不表示0 |
| `billing` | object或null | 币种、预留、实际费用及已结算费用；历史无账本任务可为null |
| `error` | object（可选） | 任务异常时返回code与message；提交未知可附cause，表示无法确认的故障类别，不证明上游未接单 |
| `warning` | object（可选） | 后台获取进度失败时返回task_refresh_delayed、message与last_failed_at；当前状态为最近已知状态，成功刷新后清除提示 |
| `request_id` | string | 本次HTTP请求追踪编号；同一任务多次查询会变化 |
| `next_poll_after_seconds` | integer | 大于0时等待对应秒数后查询；0表示停止自动轮询 |
| `result.type` | string | `video`或`text`；按结果类型读取，无需按输入模式分支 |
| `result.text` | string | Context IR的增强文本，仅type=text时返回 |
| `result.url` | string或null | 仅type=video；主视频短时签名链接，文件不可用时可为 `null` |
| `result.mime_type` | string | 仅type=video；文件真实MIME类型 |
| `result.link_expires_at` | string或null | 仅type=video；平台签名链接到期时间，UTC ISO 8601格式 |
| `result.source_expires_at` | string或null | 仅type=video；源文件到期时间；`null`表示未知，不表示永久保存 |
| `result.availability` | string | 仅type=video；`available`、`expired`或`unavailable` |
| `result.artifacts` | object\[\]（可选） | 仅type=video；只列尾帧等附加文件，不重复主视频；无附加文件时省略。每项含id/type/url/mime\_type、两种有效期和availability |
| billing\.state | string | 费用状态，见余额与计费 |
| billing\.currency | string | 账户币种；所有\_micros金额固定为微单位，1币种单位=1,000,000微单位 |
| billing\.reserved\_micros | string | 初始预留金额；历史值不等于当前冻结金额 |
| billing\.actual\_micros | string或null | 确认的实际费用；未知为null |
| billing\.settled\_micros | string或null | 已结算扣款金额；未结算为null |
| billing\.reason | string（可选） | 仅有待确认或异常原因时返回；价格版本见网页账单详情 |
`usage`仅在有已知计量时返回，可能包括输入／输出／生成Token、视频秒数、参考视频秒数、图片数和音频秒数。未知不补0，不同单位不相加。金额为微单位整数字符串，例如CNY的 `"1250000"`表示1\.250000元；用整数或Decimal计算。
### 任务受理示例
HTTP `202`受理示例，金额为演示值。状态可能为 `prepared`或 `queued`；处理中 `result=null`，未知用量和无错误时省略 `usage`、`error`。
```JSON
{
"id": "vid_ABCDEFGHIJKLMNOP",
"model": "minimax-h3",
"operation": "video.generate",
"status": "prepared",
"result": null,
"billing": {
"state": "reserved",
"currency": "CNY",
"reserved_micros": "8000000",
"actual_micros": null,
"settled_micros": null
},
"request_id": "req_ABCDEFGHIJKLMNOP",
"next_poll_after_seconds": 60
}
```
处理中查询仍返回同一结构；按返回间隔等待，不重复POST，各中间状态不保证逐一出现。
### 视频成功示例
字段说明对应下方完整响应。视频任务共用此结构；金额与签名为演示值，预留8元、最终扣款6\.5元。未知用量、无错误与无附加文件时省略对应可选字段；`result`和金额的null仍保留，用于表达尚无结果或金额未知。
```JSON
{
"id": "vid_ABCDEFGHIJKLMNOP",
"model": "minimax-h3",
"operation": "video.generate",
"status": "succeeded",
"result": {
"type": "video",
"url": "https://bytesota-api.businessmodelcraft.com/v1/tasks/vid_ABCDEFGHIJKLMNOP/content?expires=1791965700&signature=EXAMPLE_SIGNATURE",
"mime_type": "video/mp4",
"link_expires_at": "2026-10-14T08:15:00.000Z",
"source_expires_at": null,
"availability": "available"
},
"billing": {
"state": "settled",
"currency": "CNY",
"reserved_micros": "8000000",
"settled_micros": "6500000",
"actual_micros": "6500000"
},
"request_id": "req_ABCDEFGHIJKLMNOP",
"next_poll_after_seconds": 0
}
```
## 第三步：保存视频
当 `status=succeeded` 且 `result.availability=available` 时下载：
```Bash
curl --fail --location 'https://bytesota-api.businessmodelcraft.com/v1/tasks/vid_ABCDEFGHIJKLMNOP/content' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--output generated.mp4
```
也可使用返回的 `result.url`，保持签名参数完整。下载后将文件保存在自己的存储中；平台链接用于获取结果，文件保存规则见下载与保存。
没有附加文件时`result.artifacts`省略，程序按`result.artifacts ?? []`遍历。Context IR返回 `result.type=text`，读取 `result.text`，不执行视频下载。Seedance可选尾帧位于 `result.artifacts`，按其链接与可用性读取；MOV的MIME为 `video/quicktime`，按实际格式保存。
# 具体模型接入规则
各型号只需选择请求字段与示例，响应统一按通用响应字段处理。模式选择、必填条件与素材规格集中在同一字段表，SKU与价格只列于模型清单。
示例包含地址、认证、幂等键与内联JSON。替换Key、素材或源任务编号；新任务使用新幂等键，网络重试保持原键与参数。“模型专用特殊字段”标识特定型号或系列的扩展项。
## MiniMax H3
**MiniMax H3** · 以文字、首尾帧或参考素材生成视频，支持768P与2K输出。 调用名称：`minimax-h3`。
### 请求字段
| 字段 | 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ------------------------- | -------------------------------------- | ---------- | ------------------------------------ | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | minimax\-h3 | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 是 | 无 | 去首尾空白后1～7000 Unicode码点 | 所有模式必填 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5 | 4～15秒 | 不支持自动时长 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 768P | 768P / 2K | 按本行可选值选择输出分辨率 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | 文生16:9；素材adaptive | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 首尾帧省略或adaptive；参考模式可用具体比例或adaptive；文生adaptive按16:9处理 | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 首帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 尾帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 尾帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | 每项 \{url, role\} | 按role选择首帧、尾帧或参考模式；首尾帧与参考素材互斥，不重复首尾角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP；单文件≤30MiB；宽、高均256～5760像素；宽高比0\.4～2\.5 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾角色各≤1张；reference\_image与image\_urls合计≤9张；两类模式互斥 | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | 参考图 HTTPS URL | 一律参考图，与reference\_image角色合计≤9张；参考模式须至少有图片或视频，音频不能单独输入 | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤3段 | MP4 / MOV；单文件≤50MiB；单段2～15秒；视频合计≤15秒；宽、高均256～5760像素；宽高比0\.4～2\.5；23\.976～60fps | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤3段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段2～15秒；音频合计≤15秒；需搭配参考图片或视频 | 否 |
| `watermark` | 是否请求输出水印 | boolean | 否 | false | true / false | 输出AIGC水印 | 是 · H3 / H3 Max / Seedance / Wan |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅 false | true返回unsupported\_parameter | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-text-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
```
#### 首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-first-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 仅尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-last-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 首尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-frames-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考图、视频和音频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-reference-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "768P",
"aspect_ratio": "16:9",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
#### 2K输出
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-2k-001' \
--data-raw '{
"model": "minimax-h3",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 10,
"resolution": "2K",
"aspect_ratio": "9:16"
}'
```
## MiniMax H3 Max
**MiniMax H3 Max** · H3系列独立视频型号，支持480P、768P与1080P输出。 调用名称：`minimax-h3-max`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ------------------------- | -------------------------------------- | ---------- | ------------------------------------ | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | minimax\-h3\-max | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 是 | 无 | 去首尾空白后1～7000 Unicode码点 | 所有模式必填 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5 | 5～15秒 | 不支持自动时长 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 768P | 480P / 768P / 1080P | 按本行可选值选择输出分辨率；1080P须省略watermark | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | 文生16:9；素材adaptive | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 首尾帧省略或adaptive；参考模式可用具体比例或adaptive；文生adaptive按16:9处理 | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 首帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 尾帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 尾帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | 每项 \{url, role\} | 按role选择首帧、尾帧或参考模式；首尾帧与参考素材互斥，不重复首尾角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP；单文件≤30MiB；宽、高均256～5760像素；宽高比0\.4～2\.5 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾角色各≤1张；reference\_image与image\_urls合计≤9张；两类模式互斥 | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | 参考图 HTTPS URL | 一律参考图，与reference\_image角色合计≤9张；参考模式须至少有图片或视频，音频不能单独输入 | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤3段 | MP4 / MOV；单文件≤50MiB；单段2～15秒；视频合计≤15秒；宽、高均256～5760像素；宽高比0\.4～2\.5；23\.976～60fps | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤3段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段2～15秒；音频合计≤15秒；需搭配参考图片或视频 | 否 |
| `watermark` | 是否请求输出水印 | boolean | 否 | false | true / false | 1080P必须省略本字段，即使false；其他规格可选true／false | 是 · H3 / H3 Max / Seedance / Wan |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅 false | true返回unsupported\_parameter | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-text-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "768P",
"aspect_ratio": "16:9"
}'
```
#### 首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-first-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 仅尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-last-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 首尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-frames-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 6,
"resolution": "768P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考图、视频和音频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-reference-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "768P",
"aspect_ratio": "16:9",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
#### 480P输出
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-480p-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "480P",
"aspect_ratio": "16:9"
}'
```
#### 1080P输出，省略watermark
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-minimax-h3-max-1080p-001' \
--data-raw '{
"model": "minimax-h3-max",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 10,
"resolution": "1080P",
"aspect_ratio": "9:16"
}'
```
## MiniMax H3 再生成
**MiniMax H3 再生成** · 复用本人成功的H3 768P任务，继承创作输入与时长，再生成2K视频。 调用名称：`minimax-h3-regeneration`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ---------------- | -------------------------- | ------ | -------- | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | minimax\-h3\-regeneration | 固定调用名称，按示例精确填写 | 否 |
| `source_task_id` | 用于再生成的平台源任务编号 | string | 是 | 无 | 平台vid\_任务ID | 本人已成功的minimax\-h3／768P平台任务；输出2K并继承时长，只传model与source\_task\_id，不传新素材或规格 | 是 · Regeneration |
### 完整请求示例
#### 以平台源任务再生成
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-regeneration-source-001' \
--data-raw '{
"model": "minimax-h3-regeneration",
"source_task_id": "vid_ABCDEFGHIJKLMNOP"
}'
```
## MiniMax H3 Context IR
**MiniMax H3 Context IR** · 结合创作想法与可选素材，生成可用于后续视频创作的增强提示词。 调用名称：`minimax-h3-context-ir`。 返回增强文本，视频生成需另行提交。
### 请求字段
| **字段**
| **字段含义** | **类型** | **是否必选** | **默认值** | **可选值 / 范围** | **备注说明（模式与素材限制）** | **模型专用特殊字段** |
| ------------------------- | -------------------------------------- | ---------- | ------------------------------------ | ------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | minimax\-h3\-context\-ir | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 是 | 无 | 1～7000 Unicode码点 | 原始创作想法 | 否 |
| `duration` | 目标视频节奏，单位秒；本次输出文本 | integer | 否 | 5 | 4～15秒 | 目标视频节奏，不是本次输出视频时长 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 纯文本是 | 素材adaptive | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 纯文本增强必须明确具体比例；首尾帧省略或adaptive；参考可用具体比例或adaptive | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 首帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 尾帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 尾帧最多1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | 每项 \{url, role\} | 按role选择首帧、尾帧或参考模式；首尾帧与参考素材互斥，不重复首尾角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP；单文件≤30MiB；宽、高均256～5760像素；宽高比0\.4～2\.5 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾角色各≤1张；reference\_image与image\_urls合计≤9张；两类模式互斥 | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | 参考图 HTTPS URL | 一律参考图，与reference\_image角色合计≤9张；参考模式须至少有图片或视频，音频不能单独输入 | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤3段 | MP4 / MOV；单文件≤50MiB；单段2～15秒；视频合计≤15秒；宽、高均256～5760像素；宽高比0\.4～2\.5；23\.976～60fps | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤3段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段2～15秒；音频合计≤15秒；需搭配参考图片或视频 | 否 |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅false | 不接受true | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 纯文本增强
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-ir-text-001' \
--data-raw '{
"model": "minimax-h3-context-ir",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"aspect_ratio": "16:9"
}'
```
#### 首帧图片增强
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-ir-first-001' \
--data-raw '{
"model": "minimax-h3-context-ir",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 尾帧图片增强
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-ir-last-001' \
--data-raw '{
"model": "minimax-h3-context-ir",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"aspect_ratio": "adaptive",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 首尾帧图片增强
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-ir-frames-001' \
--data-raw '{
"model": "minimax-h3-context-ir",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考素材增强
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-ir-reference-001' \
--data-raw '{
"model": "minimax-h3-context-ir",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"aspect_ratio": "adaptive",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
## Seedance 2\.5
**Seedance 2\.5** · 覆盖视频生成、编辑与延长，支持声音、MOV和可选尾帧输出。 调用名称：`seedance-2.5`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| -------------------------- | -------------------------------------- | ---------- | ------------------------------------ | ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | seedance\-2\.5 | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 是 | 无 | 1～20000 Unicode码点 | 所有模式必填；edit描述编辑／删除／替换，extend描述向前／向后延长；@图片1等编号按各数组顺序 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5；edit为\-1 | 4～30秒或\-1 | \-1为自动时长；edit必须\-1，省略时也为\-1 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 720p | 480p / 720p / 1080p | 按本行可选值选择输出分辨率 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | adaptive | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 平台统一字段；首尾帧/edit/extend只接受adaptive | 否 |
| `generate_audio` | 是否生成输出视频的声音 | boolean | 否 | true | true / false | 输出是否含声音 | 否 |
| `output_format` | 输出视频的文件格式 | string | 否 | mp4 | mp4 / mov | MP4的MIME为video/mp4，MOV为video/quicktime；按实际结果保存 | 是 · Seedance |
| `return_last_frame` | 是否同时返回输出视频的尾帧图片 | boolean | 否 | false | true / false | 开启后从result\.artifacts读取可用的last\-frame图片；与尾帧输入是不同功能 | 是 · Seedance |
| `omni_reference_task_type` | 参考素材的处理方式 | string | 否 | 有参考素材reference，否则auto | auto / reference / edit / extend | 文生／首尾帧用auto；素材参考用reference；edit或extend必须有video\_urls，画幅为adaptive | 是 · Seedance |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | \{url,role\} | 首尾帧与参考模式互斥；尾帧须搭配首帧；不重复角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP / BMP / GIF；单文件≤30MiB；宽、高均300～6000像素；宽高比0\.4～2\.5 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾各≤1张；reference\_image与image\_urls合计≤30张；两类模式互斥 | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 首帧≤1张；与参考素材互斥，不与角色重复；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 首尾帧模式需提供；可用角色替代 | 无 | HTTPS URL | 尾帧≤1张且须搭配首帧；与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | ≤30张 | 一律参考图，和reference\_image合计≤30张；首尾帧用对应字段或角色 | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤10段 | MP4 / MOV；单文件≤200MiB；单段2～30秒；视频合计≤30秒；edit每段至少4秒；宽、高均300～6000像素；宽高比0\.4～2\.5；总像素409600～8295044；24～60fps | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤10段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段2～30秒；音频合计≤30秒；可单独作为参考素材 | 否 |
| `seed` | 随机种子 | integer | 否 | 未指定 | JS安全整数 | 可复现性不保证完全一致 | 是 · Seedance / Wan / Vidu |
| `watermark` | 是否请求输出水印 | boolean | 否 | false | true / false | 输出水印 | 是 · H3 / H3 Max / Seedance / Wan |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅false | true不支持 | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 480p文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-text-480p-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"output_format": "mp4"
}'
```
#### 720p文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-text-720p-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"output_format": "mp4"
}'
```
#### 1080p文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-text-1080p-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"output_format": "mp4"
}'
```
#### 首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-first-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 首尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-frames-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "adaptive",
"generate_audio": false,
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考图、视频、音频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-reference-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"omni_reference_task_type": "reference",
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
#### 纯音频参考
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-audio-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
"audio_urls": ["https://assets.example.com/reference.mp3"],
"omni_reference_task_type": "reference"
}'
```
#### 自动时长、MOV和输出尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-auto-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": -1,
"resolution": "720p",
"aspect_ratio": "adaptive",
"output_format": "mov",
"return_last_frame": true,
"generate_audio": true
}'
```
#### 编辑视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-edit-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "编辑@视频1：将背景替换为日落花园，保留主体动作和构图。",
"duration": -1,
"resolution": "720p",
"aspect_ratio": "adaptive",
"video_urls": ["https://assets.example.com/reference.mp4"],
"omni_reference_task_type": "edit",
"output_format": "mov"
}'
```
#### 延长视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-seedance-extend-001' \
--data-raw '{
"model": "seedance-2.5",
"prompt": "向后延长@视频1：让主体继续沿小径行走，保持原镜头运动。",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"video_urls": ["https://assets.example.com/reference.mp4"],
"omni_reference_task_type": "extend",
"output_format": "mov"
}'
```
## Vidu Q4 Preview
**Vidu Q4 Preview** · 以首帧或参考图片生成视频，可搭配参考音频，最高支持4K输出。 调用名称：`vidu-q4-preview`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ------------------------- | -------------------------------------- | ---------- | -------------------------------- | ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | vidu\-q4\-preview | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 参考是；首帧否 | 首帧可省略 | ≤20000 Unicode码点 | 参考模式不能为空 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5 | 3～16秒 | 无自动时长 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 720p | 540p / 720p / 1080p / 2K / 4K | 按本行可选值选择输出分辨率 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | 参考16:9；首帧adaptive | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive（仅首帧） | 首帧省略或adaptive；参考不接受adaptive | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧模式需提供；可用对应角色替代 | 无 | 1张HTTPS图片 | 首帧恰好1张；不能搭配参考图或音频；图片规格见image\_with\_roles\[\]\.url | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 图片必需；可用其他图片字段替代 | 无 | 1～15张参考图 | 一律作为参考图，单张也不推导为首帧；与reference\_image角色合计1～15张，参考模式prompt必填；首帧使用first\_frame\_image | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 图片必需；可用其他图片字段替代 | 无 | \{url,role\} | 首帧模式恰好1张、不能搭配参考素材；参考模式1～15张且prompt必填 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP；单文件≤50MiB；可读取有效宽高；不搭配其他参考素材 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / reference\_image | 首帧恰好1张；参考图合计≤15张；不接受尾帧、参考视频或纯文字模式 | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤3段MP3 | MP3（含Xing/Info）；单文件≤50MiB；单段3～12秒；音频合计≤36秒；仅参考图片模式可用 | 否 |
| `generate_audio` | 是否生成输出视频的声音 | boolean | 否 | true | true / false | 输出音轨，不是参考音频字段 | 否 |
| `seed` | 随机种子 | integer | 否 | 未指定 | JS安全整数 | 随机种子 | 是 · Seedance / Wan / Vidu |
### 完整请求示例
#### 540p首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-540p-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "540p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 720p首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-720p-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 1080p首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-1080p-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "adaptive",
"generate_audio": true,
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 2K首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-2K-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "adaptive",
"generate_audio": true,
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 4K首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-4K-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "4K",
"aspect_ratio": "adaptive",
"generate_audio": true,
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 首帧，省略提示词
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-first-no-prompt-001' \
--data-raw '{
"model": "vidu-q4-preview",
"duration": 5,
"resolution": "720p",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 单张参考图与音频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-vidu-reference-001' \
--data-raw '{
"model": "vidu-q4-preview",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "1080p",
"aspect_ratio": "9:16",
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"generate_audio": true,
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
## Wan 3\.0
**Wan 3\.0** · 支持文字、首尾帧及图片、视频、音频参考，提供2～30秒视频生成。 调用名称：`wan-3.0`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ------------------------- | -------------------------------------- | ---------- | ---------------------------------------- | ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | wan\-3\.0 | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 文生是；有素材否 | 有素材可省略 | ≤20000 Unicode码点 | 文生必填；首尾帧或参考素材模式可省略；超长拒绝，不截断 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5 | 2～30秒或\-1 | 参考视频输入总时长\+固定输出时长≤30秒；\-1为自动时长 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 720P | 480P / 720P / 1080P | 按本行可选值选择输出分辨率 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | adaptive | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 平台统一字段；首尾帧只接受adaptive | 否 |
| `generate_audio` | 是否生成输出视频的声音 | boolean | 否 | true | true / false | 输出是否含声音 | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | ≤10张参考图 | 一律作为参考图，单张也不推导为首帧；与reference\_image角色合计≤10张；首尾帧使用明确字段，与参考模式互斥 | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | \{url,role\} | 按角色选择首尾帧或参考；两类互斥，不重复首尾角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP / BMP；单文件≤20MiB；宽、高均240～8000像素；宽高比1:8～8:1；PNG必须可确认无透明通道 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾各≤1张；参考图和image\_urls合计≤10张；首尾帧模式不搭配参考音视频 | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用对应角色替代 | 无 | 首帧URL | 首帧≤1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 尾帧／首尾帧模式需提供；可用对应角色替代 | 无 | 尾帧URL | 尾帧≤1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤5段 | MP4 / MOV；单文件≤100MiB；单段1～15秒；视频合计≤15秒；宽、高均240～4096像素；宽高比1:8～8:1 | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤5段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段1～15秒；音频合计≤15秒；可单独作为参考素材 | 否 |
| `seed` | 随机种子 | integer | 否 | 未指定 | 0～2147483647 | 随机种子 | 是 · Seedance / Wan / Vidu |
| `watermark` | 是否请求输出水印 | boolean | 否 | false | true / false | 输出水印 | 是 · H3 / H3 Max / Seedance / Wan |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅false | true不支持 | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 480P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-text-480P-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "480P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 720P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-text-720P-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 1080P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-text-1080P-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "1080P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-first-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 仅尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-last-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "adaptive",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 首尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-frames-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "1080P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考素材
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-reference-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"generate_audio": false,
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
#### 自动时长
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-auto-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": -1,
"resolution": "480P",
"aspect_ratio": "adaptive",
"generate_audio": true
}'
```
## Wan 3\.0 Prime
Wan 3.0与Prime有参考视频时，输入视频总秒数与输出秒数分别计费，二者共用对应输出分辨率的现有每秒售价。例如Wan 3.0 480P参考输入5秒、固定输出2秒，按7秒×USD 0.033=USD 0.231计费。输入时长由平台解析素材核验，不接受自报计量；自动输出按实际输出时长结算。只影响新报价，历史任务保留原快照。
**Wan 3\.0 Prime** · Wan系列Prime独立型号，沿用Wan参数规则，权限与价格分别配置。 调用名称：`wan-3.0-prime`。
### 请求字段
| 字段
| 字段含义 | 类型 | 是否必选 | 默认值 | 可选值 / 范围 | 备注说明（模式与素材限制） | 模型专用特殊字段 |
| ------------------------- | -------------------------------------- | ---------- | ---------------------------------------- | ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `model` | 调用型号的接口标识 | string | 是 | 无 | wan\-3\.0\-prime | 固定调用名称，按示例精确填写 | 否 |
| `prompt` | 描述内容、动作、镜头或编辑意图的提示词 | string | 文生是；有素材否 | 有素材可省略 | ≤20000 Unicode码点 | 文生必填；首尾帧或参考素材模式可省略；超长拒绝，不截断 | 否 |
| `duration` | 输出视频时长，单位秒 | integer | 否 | 5 | 2～30秒或\-1 | 参考视频输入总时长\+固定输出时长≤30秒；\-1为自动时长 | 否 |
| `resolution` | 输出视频分辨率 | string | 否 | 720P | 480P / 720P / 1080P | 按本行可选值选择输出分辨率 | 否 |
| `aspect_ratio` | 输出画幅宽高比 | string | 否 | adaptive | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 平台统一字段；首尾帧只接受adaptive | 否 |
| `generate_audio` | 是否生成输出视频的声音 | boolean | 否 | true | true / false | 输出是否含声音 | 否 |
| `image_urls` | 图片地址数组 | string\[\] | 否 | 无 | ≤10张参考图 | 一律作为参考图，单张也不推导为首帧；与reference\_image角色合计≤10张；首尾帧使用明确字段，与参考模式互斥 | 否 |
| `image_with_roles` | 明确指定图片用途的数组 | object\[\] | 否 | 无 | \{url,role\} | 按角色选择首尾帧或参考；两类互斥，不重复首尾角色 | 否 |
| `image_with_roles[].url` | 数组内单张图片的地址 | string | 数组内是 | 无 | HTTPS URL | 所有图片字段统一要求：PNG / JPEG / WebP / BMP；单文件≤20MiB；宽、高均240～8000像素；宽高比1:8～8:1；PNG必须可确认无透明通道 | 否 |
| `image_with_roles[].role` | 数组内图片的用途 | string | 数组内是 | 无 | first\_frame / last\_frame / reference\_image | 首尾各≤1张；参考图和image\_urls合计≤10张；首尾帧模式不搭配参考音视频 | 否 |
| `first_frame_image` | 约束视频开始画面的图片地址 | string | 首帧／首尾帧模式需提供；可用对应角色替代 | 无 | 首帧URL | 首帧≤1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `last_frame_image` | 约束视频结束画面的图片地址 | string | 尾帧／首尾帧模式需提供；可用对应角色替代 | 无 | 尾帧URL | 尾帧≤1张，与参考素材互斥；图片规格见image\_with\_roles\[\]\.url | 否 |
| `video_urls` | 参考视频地址数组 | string\[\] | 否 | 无 | ≤5段 | MP4 / MOV；单文件≤100MiB；单段1～15秒；视频合计≤15秒；宽、高均240～4096像素；宽高比1:8～8:1 | 否 |
| `audio_urls` | 参考音频地址数组 | string\[\] | 否 | 无 | ≤5段 | PCM WAV / MP3（含Xing/Info）；单文件≤15MiB；单段1～15秒；音频合计≤15秒；可单独作为参考素材 | 否 |
| `seed` | 随机种子 | integer | 否 | 未指定 | 0～2147483647 | 随机种子 | 是 · Seedance / Wan / Vidu |
| `watermark` | 是否请求输出水印 | boolean | 否 | false | true / false | 输出水印 | 是 · H3 / H3 Max / Seedance / Wan |
| `nsfw_check` | 额外审核选项，本版仅接受false | boolean | 否 | false | 仅false | true不支持 | 是 · 除Vidu与Regeneration外的型号 |
### 完整请求示例
#### 480P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-text-480P-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "480P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 720P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-text-720P-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 1080P文生视频
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-text-1080P-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "1080P",
"aspect_ratio": "16:9",
"generate_audio": true
}'
```
#### 首帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-first-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png"
}'
```
#### 仅尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-last-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "adaptive",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 首尾帧
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-frames-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 8,
"resolution": "1080P",
"aspect_ratio": "adaptive",
"first_frame_image": "https://assets.example.com/first.png",
"last_frame_image": "https://assets.example.com/last.png"
}'
```
#### 参考素材
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-reference-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"video_urls": [
"https://assets.example.com/reference.mp4"
],
"audio_urls": [
"https://assets.example.com/reference.mp3"
],
"generate_audio": false,
"image_urls": [
"https://assets.example.com/reference.png"
]
}'
```
#### 自动时长
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-wan-3.0-prime-auto-001' \
--data-raw '{
"model": "wan-3.0-prime",
"prompt": "小猫沿花园小径向前走，镜头缓缓跟随。",
"duration": -1,
"resolution": "480P",
"aspect_ratio": "adaptive",
"generate_audio": true
}'
```
# 平台任务与文件规则
## 任务状态
| status | 含义 | 自动查询 | 处理 |
| ---------------------- | ------------------------ | ------------------------------- | -------------------------------- |
| `prepared` | 已接收，平台等位 | 按返回值，通常60秒 | 保存编号，不重复提交 |
| `submitting` | 正在提交 | 按返回值，通常60秒 | 等待同一任务 |
| `queued` / `running` | 已受理／生成中 | 按返回值，基准30秒 | 不提高查询频率催促生成 |
| `succeeded` | 生成或增强完成 | 费用补查时至少60秒；返回0则停止 | 读取结果，单独检查文件和费用状态 |
| `failed` / `cancelled` | 明确失败／取消或排队到期 | 0，停止 | 查看错误与预留释放状态 |
| `submission_unknown` | 提交结果无法确认 | 0，停止 | 联系支持，不用新键重复生成 |
`next_poll_after_seconds>0`表示至少等待相应秒数，0表示停止自动轮询。平台自动推进任务；停止查询不等于取消。HTTP 429按 `Retry-After`等待后重试原操作。
## 下载与保存
| 项目 | 规则 |
| ------------------ | ----------------------------------------------------------------------------------- |
| 主视频／附加文件 | 使用对应签名链接，或Bearer访问 `/content`、`/artifacts/{artifact_id}/content` |
| 签名链接 | 保留全部参数；`link_expires_at`到期后查询任务获取新链接 |
| 源文件 | `source_expires_at`为源期限，null表示未知；刷新链接不延长源文件保存期 |
| 文件状态 | `available`可读取；`expired`已过期；`unavailable`不可用 |
| 410 artifact\_gone | 源文件不可用，不自动重新生成或退款；成功状态仍保留 |
| 长期保存 | 及时下载到自己的存储，平台不承诺永久托管 |
| 文件格式 | 按实际MIME保存；改变后缀不会转换格式 |
| HEAD／Range | 支持HEAD与单段字节Range，返回206／416；HEAD错误读取 `X-Error-Code`与 `X-Request-Id` |
| 查询与文件权限 | 仅本人任务；不存在或他人任务返回404；账户停用后既有签名也失效 |
| 权限撤销 | 仍有效账户可查询本人历史任务；控制台只读会话不能用于生成 |
| 回调与取消 | 本版无Webhook或客户自助取消接口 |
# 报错速查
HTTP非2xx表示本次操作未正常确认；错误响应仍可能包含已创建任务的 `id`、`status`、`billing`。查询HTTP `200`但 `status=failed`表示查询成功、生成失败；`submission_unknown`表示采购结果未知，不是确定未接单。按 `error.code`处理，不匹配message文案做逻辑判断；可选 `error.param`定位字段（可含数组索引）。所有统一错误带 `X-Error-Code`、`X-Request-Id`，HEAD通过响应头定位。排障提供任务编号、`request_id`、错误码和时间，不发送完整Key。
提交未知时 `error.code=submission_unknown`，可选 `error.cause`区分超时、响应异常、服务故障或平台存储故障。首次提交及同键重放返回相应502/503/504，GET仍返回200和同一个任务。保持原参数与幂等键，不能因HTTP错误改用新键重复生成。
查询返回 `warning.code=task_refresh_delayed`表示暂时无法获取最新进度，不表示生成失败；`warning.last_failed_at`是最近失败观察的UTC时间。继续按原任务的轮询建议查询，不重复提交。
错误响应示例：
```JSON
{
"error": {
"code": "invalid_request",
"message": "该字段的类型、取值或组合不符合模型要求",
"param": "resolution"
},
"request_id": "req_ABCDEFGHIJKLMNOP"
}
```
| HTTP | 错误码 | 含义 | 处理方法 | 能否重试 / 如何重试 | 费用影响 |
| --------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------- | ---------------------------------------------- | ------------------------------------------------ |
| 400 | `invalid_request` / `unsupported_model` | 字段、类型、组合或型号不合法 | 对照对应SKU字段表修正 | 修正后提交；已有任务不得同键改参数 | 被拒绝请求不创建新的收费任务 |
| 400 | `invalid_media` / `media_metadata_unavailable` | 素材不符合要求或无法解析 | 检查域名、最终URL、格式、大小和真实元数据 | 修正素材后提交；不要原样高频重试 | 被拒绝请求不产生新任务费用 |
| 400 | `unsupported_parameter` | 请求包含未支持的选项 | 删除或调整该选项 | 修正后提交 | 被拒绝请求不产生新任务费用 |
| 400 | `invalid_source_task` | 再生成源任务不符合条件 | 核对归属、型号、状态与分辨率 | 使用合格源任务后提交 | 被拒绝请求不产生新任务费用 |
| 401 | `invalid_api_key` | Key无效或账户不可用 | 检查Key与账户状态，联系支持 | 修正后重试原操作 | 不新建任务；已有任务费用另行查询 |
| 402 | `insufficient_balance` | 可用余额不足 | 充值并确认入账 | 入账后重试尚未接收的原请求 | 本次拒绝不创建新预留；其他任务冻结仍保留 |
| 403 | `model_not_allowed` | 账户未获该型号权限 | 联系服务方开通 | 权限就绪后重试 | 本次拒绝不产生新任务费用 |
| 404 | `task_not_found` | 编号不存在或不属于本人 | 核对平台任务编号与账户 | 修正查询，不提交重复生成 | 查询不产生生成费用 |
| 409 | `idempotency_conflict` | 同一键对应不同参数 | 恢复原参数；新业务动作使用新键 | 不原样重试冲突请求 | 不生成第二个任务；原任务费用仍有效 |
| 409 | `task_not_ready` | 文件尚未就绪 | 先查询任务状态 | 等待后重试原下载 | 不重复生成或扣款 |
| 409 | `billing_currency_mismatch` / `billing_limit_exceeded` | 币种或预留上限不匹配 | 联系服务方核对报价配置 | 配置确认后重试 | 本次拒绝不创建新预留 |
| 410 | `artifact_gone` | 源文件已不可用 | 检查是否已自行保存结果 | 刷新链接不能恢复已删除源文件 | 不自动重做或退款 |
| 413 | `request_too_large` | 请求JSON超过大小上限 | 将JSON控制在64KiB以内 | 修正后提交 | 本次拒绝不产生新任务费用 |
| 415 | `unsupported_media_type` | 请求Content\-Type不正确 | 生成接口使用JSON | 修正后提交 | 本次拒绝不产生新任务费用 |
| 429 | `request_rate_exceeded` / `queue_full` / `quota_exceeded` | 频率、队列容量或额度受限 | 遵守 `Retry-After`；额度不足联系服务方 | 等待后原操作重试；提交保留原键 | 不产生重复任务；已存在任务仍按原状态计费 |
| 429 | `purchase_budget_exceeded` | 当日销售预留预算不足 | 核对本Key与全局预算，联系服务方或等待次日 | 先查询已有任务，提交保留原键，不用新键重复采购 | 预算、余额与最终消费不同；已有任务按实际状态处理 |
| 503 | `generation_disabled` / `model_disabled` | 服务或型号暂停 | 联系服务方确认恢复时间 | 恢复后原请求重试 | 不创建新的生成意图；已受理任务另行查询 |
| 503 | `billing_unconfigured` / `configuration_incomplete` | 账户、价格或服务配置未就绪 | 联系服务方 | 配置就绪后重试 | 本次拒绝不创建新预留 |
| 503 | `capacity_busy` | 当前操作繁忙 | 按 `Retry-After`等待 | 重试原操作；POST保留原键 | 不重复创建任务；已接收任务费用以查询为准 |
| 502 / 503 / 504 | 查询或下载暂时不可用 | 网关或文件读取暂时异常 | 对原GET / HEAD退避重试 | 可以，勿改为重新生成 | 不产生新生成费用 |
| 500 / 503 | `internal_error` / `storage_unavailable` | 服务异常，提交是否完成需核实 | 保留请求ID；POST用原键确认；联系支持 | 不使用新键盲目提交 | 不能仅凭HTTP错误判断无任务、无冻结或无费用 |
| 400 | `invalid_request`（生成服务结构化参数拒绝） | 已建立任务后确认参数不合格 | 核对字段要求，修正后使用新业务键 | 原键仅找回失败任务，不会重新采购 | 已失败任务预留released |
| 403 | `content_policy_violation` | 生成内容被明确规则拒绝 | 调整内容；原键确认原失败任务 | 新内容使用新业务键 | 明确失败时释放预留 |
| 503 | `upstream_authentication_error` / `upstream_permission_error` / `upstream_insufficient_balance` | 生成服务的身份、权限或支付条件未就绪 | 联系维护者；无需更换平台Key或因此充值 | 原键只找回已有失败任务；恢复后新生成是新业务 | 提交明确拒绝则released |
| 502 | `upstream_request_rejected` | 生成服务明确拒绝，原因不足以归责客户 | 凭任务编号联系维护者 | 不要原样连续重试 | 明确拒绝则released |
| 502 / 503 / 504 | `submission_unknown` | 提交结果尚未确认，cause表示故障类别 | 查原任务并联系维护者 | 保留原键；不换新键、不自动重新采购 | 冻结保留，不能视为免费 |
| 200（GET） | `generation_failed` / `generation_cancelled` / `content_policy_violation` | 查询成功但生成失败或取消 | 停止轮询，核对费用状态 | 不重试原生成动作 | 明确失败/取消则released |
任务生成失败的完整响应示例（查询HTTP 200，停止轮询，原预留已释放）：
```JSON
{
"id": "vid_ABCDEFGHIJKLMNOP",
"model": "minimax-h3",
"operation": "video.generate",
"status": "failed",
"result": null,
"billing": {
"state": "released",
"currency": "CNY",
"reserved_micros": "8000000",
"actual_micros": null,
"settled_micros": null
},
"error": {
"code": "generation_failed",
"message": "生成失败，请查看费用状态并凭任务编号联系维护者"
},
"request_id": "req_QRSTUVWXYZabcdef",
"next_poll_after_seconds": 0
}
```
提交超时或结果不明，先用原JSON与原幂等键确认任务；HTTP错误不能单独证明无任务、无冻结或无费用。
# 余额与计费
采用预充值方式，付款经服务方核实后入账，以充值流水与可用余额增加为准。每个账户一种币种，不自动换汇。当前运营使用 USD；下文含 CNY/元的响应与金额为合成说明，不是实时售价或账户余额。每个 Key 默认每日 100 USD 销售预留预算，可由运营调整；余额、次数和预算分别生效，达到预算返回 purchase_budget_exceeded。
| 项目 / billing\.state | 金额含义与处理 |
| --------------------- | --------------------------------------------------- |
| 账户余额 | 充值与结算后的余额，包含冻结部分 |
| 可用余额 | 账户余额减冻结，用于新任务 |
| `reserved` | 已预留；排队也冻结，尚非最终消费 |
| `settled` | 成功且用量完整，扣实际费用并释放预留差额 |
| `released` | 明确失败或确定未提交的取消，预留解除，本次未收费 |
| `pending_usage` | 结果可先使用，计费用量待确认；保留冻结，不把未知补0 |
| `overage_pending` | 超预留或结算异常，保留冻结待核对，不自动透支 |
| `refunded` | 已结算后退款，保留原消费与退款流水 |
| `legacy_unbilled` | 历史任务无本版账单，不补造收费 |
| 提交结果未知 | 保留冻结，联系支持核实，不重复生成 |
同键重放不重复冻结或扣款。任务按创建时的价格结算，后续调价不追溯；价格版本见账单详情，计量项目见SKU清单。输入／输出Token分别计价，不同单位不相加，生成处理耗时不作为视频时长。
金额以整数微单位字符串返回，精度为6位小数；每个费用项向上舍入到微单位后汇总。媒体时长四舍五入到微秒，与金额舍入分别处理。
以下为余额变化示例，不是模型报价：
| 时点 | 账户余额 | 冻结 | 可用余额 | 本任务消费 |
| ---------------- | --------- | ------- | --------- | ---------- |
| 初始 | 100\.00元 | 0\.00元 | 100\.00元 | 0\.00元 |
| 预留8元 | 100\.00元 | 8\.00元 | 92\.00元 | 0\.00元 |
| 成功，结算6\.5元 | 93\.50元 | 0\.00元 | 93\.50元 | 6\.50元 |
冻结不是扣款，释放1\.5元差额也不是新增充值或退款。
# 网页控制台
入口：`https://bytesota.businessmodelcraft.com/console/`，使用平台 API Key 登录。
| 功能 | 用途 |
| -------- | ---------------------------------------- |
| 账户概览 | 查看余额、冻结、可用金额与累计消费 |
| 调用记录 | 按日期、型号、任务与费用状态筛选 |
| 费用明细 | 查看用量、单价、单位、价格版本与结算结果 |
| 账户流水 | 查看充值、预留、扣费、释放与退款 |
控制台只读，时间显示北京时间；会话过期后重新登录。登录区域下方可直接查看公开价格，无需 Key；本人余额、调用和流水仍须登录。价格仅供查阅，不授予模型调用权限。
# 低成本接入测试
**全模型首轮：8个成功任务（7个视频＋1个增强文本），每个调用型号各1次。** 不需要遍历全部规格；后续只补测业务实际使用的模式和规格。
先携Key调用 `GET /v1/models`，确认目标型号enabled、allowed为true，价格已配置、余额足够。按下表串行测试，先用Wan验证公共链路，再测其他型号；实际费用以模型清单的正式报价和最终用量为准。
| **顺序** | **调用型号** | **首轮模式与最小参数** | **素材与复用** | **费用控制** |
| -------- | ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 1 | `wan-3.0` | 纯文本；`duration=2`、`resolution=480P`、`aspect_ratio=1:1` | 无素材；保存2秒成片供后续参考 | 标准版2秒×480P单价；同时验提交、查询、下载、幂等与账单 |
| 2 | `minimax-h3-context-ir` | 短文本增强；`duration=4`、`aspect_ratio=1:1` | 无素材；增强文本可用于后续任务 | 输入、输出Token分别计费；短提示词，不加素材；duration只描述目标节奏，不限制输出Token |
| 3 | `wan-3.0-prime` | 纯文本；`duration=2`、`resolution=480P`、`aspect_ratio=1:1` | 无素材 | Prime版2秒×480P单价；标准版成功不能代替Prime适配 |
| 4 | `vidu-q4-preview` | 首帧；`duration=3`、`resolution=540p`、`aspect_ratio=adaptive` | `first_frame_image`传1张自备图片 | 3秒×540p单价；必须有图，不另付费生成图片，不传音频 |
| 5 | `minimax-h3-max` | 纯文本；`duration=5`、`resolution=480P`、`aspect_ratio=1:1` | 无素材 | 5秒×480P单价；与H3分别验证 |
| 6 | `minimax-h3` | 纯文本；`duration=4`、`resolution=768P`、`aspect_ratio=1:1` | 保存本人成功任务id，供下一步使用 | 4秒×768P单价；不直接生成2K，不传参考素材 |
| 7 | `minimax-h3-regeneration` | 仅传 `model`与 `source_task_id`；继承4秒、输出2K | 复用第6步H3任务，不另建源任务 | 4秒×再生成单价；源视频计量规则见报价；不用Max或Wan任务替代H3源 |
| 8 | `seedance-2.5` | 纯文本；`duration=4`、`resolution=480p`、`aspect_ratio=1:1` | 默认无素材；有更低价参考档时，可复用第1步2秒成片，传 `video_urls`、`omni_reference_task_type=reference` | 比较纯文本4秒与参考输入2秒＋输出4秒的报价，选预计总费用较低者；最终按completion\_tokens结算 |
**综合省钱：** 每个型号只新增1个任务，复用H3源任务和自备图片。Seedance参考档只有在计入输入时长后仍更便宜、素材满足其尺寸／帧率要求且链接可公开访问时才选用；不为优惠档额外生成视频。全轮预算按上述8项预计费用相加，Token任务留出余量。
**统一验收：** 每个任务按 `next_poll_after_seconds`查询，返回0停止自动轮询；成功后视频验证可播放，IR读取 `result.text`。首个Wan任务完整验证下载、同键同参数重试不重复生成或扣费；其余任务复用同一客户端流程，逐一确认结果、用量与最终结算。非默认模式仅按业务需要补测；一条成功任务只证明该型号的本次模式与规格。
## 最小规格完整请求
替换Key，首次测试使用新幂等键。该测试直接生成视频，不先调用提示词增强，也不传图片、视频或参考音频。
```Bash
curl --request POST 'https://bytesota-api.businessmodelcraft.com/v1/videos/generations' \
--header 'Authorization: Bearer YOUR_PLATFORM_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: connectivity-wan-480p-2s-001' \
--data-raw '{
"model": "wan-3.0",
"prompt": "日光下，一片绿叶随微风轻轻摆动，镜头固定。",
"duration": 2,
"resolution": "480P",
"aspect_ratio": "1:1",
"generate_audio": false
}'
```
声音开关用于选择输出，不代表关闭声音会降价。首轮显式指定最低分辨率与最短固定时长，不开可选尾帧输出；参考素材仅在上表要求或确认更省钱时使用。遇到超时或submission\_unknown时保留原键和参数核实，不换键重复生成；仅在明确失败、排查完成后，才用新键再试。
## 本地视频临时上传
图片接口不变。视频先上传，再将返回reference填入支持视频参考的型号的video_urls，生成仍使用JSON和独立Idempotency-Key：
```bash
curl -X POST 'https://bytesota-api.businessmodelcraft.com/v1/uploads/videos' \
-H 'Authorization: Bearer YOUR_PLATFORM_KEY' \
-F 'file=@reference.mp4;type=video/mp4'
```
仅支持一个file，无额外字段，MP4/H264或H265、50MiB、最长30秒；具体型号会再次检查数量、总时长、分辨率与模式。读取metadata.seconds是平台解析值，不能自行填时长绕过核验。音频本地上传尚未提供。
生成示例（字段默认值以本人/v1/models为准）：
```json
{
"model": "seedance-2.5",
"prompt": "按参考视频的动作生成新场景",
"video_urls": ["media://med_REPLACE_WITH_ID_"]
}
```
默认24小时内可新建任务，new_task_usable_until提前一分钟；已关联的排队/提交未知/生成中任务保护原对象，全部关联任务结束后1小时清理。保护期间expires_at为null、protected_by_active_task=true；usable_for_new_task仍可能为false，不表示可以无限新建任务。素材清理后须重新上传，原终态幂等重放不受影响。
GET /v1/media/usage使用本人Bearer Key，返回count、bytes、max_count=100、max_bytes=209715200；图片视频合并计量。删除未确认的对象仍计入，避免虚报容量已释放。DELETE /v1/media/{id}仅支持本人R2视频：200表示删除已确认，202表示已停止使用但物理清理待重试，409/media_in_use表示仍有任务保护。不要为解决容量而反复上传；unknown时查询原media_id，不自动重传。
返回给调用者的是不透明reference；供应商拉取链接由平台发送时生成，不要把本地路径、Base64或自建asset://放进生成请求。