# .motion 模板火山视频 API

服务入口：`https://motiongit.com`。模型 `seedance-2.0`，能力 `videos.generate`。接口为 `.motion` 模板制作本期视频素材；素材下载后按模板 guide/schema 绑定到视频槽，预览并检查成片。

调用前读取公开 `GET /api/v1/capabilities` 和本人 `GET /api/v1/usage`。仅当目录 `status=ready`、本人对应模型 `available=true` 且预算充足时提交。

## 用户 Key

传入 **MotionGit 平台用户 Key**，通过请求头 `Authorization: Bearer <Key>`；不需要火山 Key。权限须含 `videos.generate`、`usage.read`、`assets.read`，模型白名单须允许 `seedance-2.0`。配音专用 Key 不自动扩权。个人 `.motion` 模板使用原包随附工具调用，不能手拆包内凭据；缺权限时由用户在网站设置。

## 输入与计费

```json
{"capability":"videos.generate","model":"seedance-2.0","input":{"prompt":"蓝色陶瓷杯置于木桌上，自然光，镜头缓慢推进，无人物、无文字。","duration":5,"resolution":"480p","ratio":"16:9","generate_audio":false}}
```

- `prompt`：必填，不超过2000字符。
- `duration`：5、10、15秒；默认5。
- `resolution`：480p、720p、1080p；默认720p。
- `ratio`：16:9、9:16、1:1；默认16:9。
- `generate_audio`：布尔值，默认true；不需要声音时明确false。
- 当前网站只支持文生视频，不接收 `seed`、参考图、参考视频、参考音频或任意供应商参数。

当前分辨率报价为6、13、32点/秒，按供应商参考成本约上浮30%并取整；5秒分别30、65、160点。最终读取当次报价的 `max_credits`，不要把文档数字写死。后台可按新的价格版本调整，已报价任务保留原上限。实际供应商成本另按返回 `completion_tokens` 记录，不能把平台点数视作供应商余额。

视频属于第三方付费接口，需要积分。免费素材的每日30次/账号请求额度与此分开；Key预算、账户余额、并发和平台供应商日预算仍需通过 `/usage` 检查。`platform_provider_daily_credits_remaining` 是平台负载与费用保护额度，不能解释为火山剩余余额。

## 调用顺序

1. `POST /api/v1/quotes`：正文如上，不生成、不扣点。保存返回的 `quote_id`、规范化后的 `input`、`max_credits` 和 `price_version`。
2. 预算确认后 `POST /api/v1/generations`：正文包含 `quote_id`、`capability`、`model`、报价返回的原 `input`、`max_credits`；请求头同时传 `Idempotency-Key: <本次操作固定UUID>`。返回 `task_id`。
3. 每隔5秒 `GET /api/v1/tasks/<task_id>`；收到任务编号后只查询同一任务，不重复生成。任务可能需要数分钟。
4. `status=succeeded` 后读取 `result_assets`，使用相同用户 Key 下载 `GET /api/v1/assets/<asset_id>/download`。得到MP4，按 `actual_specs` 的宽高、帧率和实际毫秒时长制作。
5. `GET /api/v1/tasks/<task_id>/receipt` 查询预占、扣点、退款记录。结果默认保留30天，及时保存到本期制作目录。

网络超时时用同一 UUID 和相同正文重放提交；收到 `reconciling` 时查询原任务并检查账单，不能换 UUID 再提交。失败状态须按任务与收据处理，不能把失败任务当作已生成素材。

## 随包工具

```sh
node assistant/motion.mjs api /原始个人模板.motion usage
node assistant/motion.mjs api /原始个人模板.motion quote /本期实例/video-query.json /本期实例/video-state.json
```

继续使用包内工具支持的 `submit → task → receipt → download` 操作，并遵守该工具的状态文件与确认参数。HTTP调用使用上方合同；两条路径接入相同网站服务。