MotionGit 素材 API：各助手统一调用合同
更新时间：2026-10-09。Seedream 已移除；当前 Fal 因余额耗尽关闭，Seedance专用凭据已创建并配置，鉴权检查通过；核价和真实生成验收尚未完成。新接口合同已实现，但这些模型尚不可调用；后台明确显示原因。正式站入口 https://motiongit.com。先读取在线能力目录与本人额度，只有 status=ready 且 available=true 的模型才可使用。代码实现不等同供应商真实验收；最新验收结果见 本次报告。
用户 Key 与权限
私有请求一律使用 Authorization: Bearer <用户 MotionGit 平台 Key>。Key 从 网站 API 设置 创建；供应商密钥由服务器持有，助手不用索取或传入。Key 不放 URL、聊天、日志或 Git。.motion 工程只保存模型与参数合同，不包含任何密钥；运行时从用户私有配置读取。
每种生成权限还需 usage.read 查询任务、assets.read 下载；语音识别需 assets.read，上传需 assets.write。模型白名单必须含目标模型。现有 TTS Key 和音乐检索 Key 不自动扩权，生成其他素材应创建独立受限 Key。
- 本机已存在 TTS 配置
/Users/michael/.config/motiongit/tts.env，客户端/Users/michael/.local/share/motiongit/tts.mjs；仅能调用volc-tts。 - 本机已存在音乐配置
/Users/michael/.config/motiongit/music.env；用于授权音乐库检索与选用。 - 使用这些文件时直接读取，禁止打印文件内容。不存在统一生成 Key 时，应在网站创建，不能假设 TTS Key 可生成视频。
先获取状态与剩余额度
GET /api/v1/capabilities 是公开目录，返回 models[].id, capability, status, reason, limits, price_options。
GET /api/v1/usage 需要 usage.read，主要字段：
| 字段 | 含义 |
|---|---|
credits.remaining | 账户可用平台点数，已扣除预占 |
credits.held | 正在处理任务预占的点数 |
key_limits.daily_remaining/monthly_remaining | 当前 Key 的日/月可用额度，null 或缺失表示未设置该上限 |
account_limits | 账户级别日/月与单次上限 |
effective_credits_remaining | 账户余额、Key 日/月、账户日/月共同限制后的平台额度 |
max_request_credits | 在上述额度基础上再计入单次上限 |
models[].key_permitted | 当前 Key 是否有该能力及模型权限 |
models[].available | 服务已开放且当前 Key 允许调用；不保证供应商实时可用 |
models[].platform_provider_daily_credits_remaining | 网站对该供应商设置的共享日预算，单位为平台点数 |
models[].capacities[].remaining_units | 按当前单价能使用的剩余计费单位；各模型共享同一余额，不能相加 |
models[].capacities[].max_units_per_request | 单次最多可报价的计费单位；实际还受 limits 的长度/时长上限限制 |
models[].unit | image 张、video 段、second 秒、minute 分钟、100_codepoints 每100字计费块 |
models[].provider_quota.known | 当前为 false；网站不推测供应商账户剩余次数、时长或余额 |
concurrency | 当前账户运行任务数与同时任务上限4 |
免费模型的 remaining_units=null, free=true 表示不按点计费，不代表无限请求；仍受频率、授权与服务状态限制。minimum_units 应结合 limits 判断是否足够制作一次素材。TTS 按 Unicode 码点每100字向上取整；ASR 按上传音频实际时长每分钟向上取整。点数是网站额度，不能当人民币或供应商余额。
模型与输入
下表描述调用合同，是否已开放必须读在线目录。
| 能力 / model | input 示例 | 输出 |
|---|---|---|
tts.speak / volc-tts | {"text":"口播文字","voice":"zh_female_shuangkuaisisi_moon_bigtts","sample_rate":24000} | 24kHz 单声道 PCM WAV，实际毫秒时长 |
images.generate / native-image | {"prompt":"图片描述","size":"1024x1024","count":1} | 图片资产；支持尺寸以目录为准 |
music.generate / fal-music | {"prompt":"适合科技讲解的安静钢琴配乐","duration":8} | 原创 WAV；8–120整数秒，实际时长以输出为准 |
sfx.generate / fal-sfx | {"prompt":"轻盈转场呼啸声","duration":3,"loop":false} | MP3；1–22整数秒 |
asr.transcribe / fal-asr | {"asset_id":"ast_本人音频ID"} | transcription.text, language_code, words；字词时间单位秒 |
videos.generate / fal-wan | {"prompt":"镜头描述","resolution":"480p","ratio":"16:9"} | MP4 固定短片；实际时长、画幅、帧率在资产规格中 |
音乐生成使用纯音乐提示词，但供应商未保证永远无声乐，最终应试听。Wan 只开放480p，不接收 duration 或 generate_audio；不能承诺精确目标时长或音轨。Seedance 与 Wan 是不同模型，不能把替代模型的结果标记成 Seedance。
ASR 只接受本人已校验且未过期的 audio/wav 或 audio/mpeg 音频资产，最长120秒；不接受其他用户资产或任意外部 URL。调用时不用伪造 duration，服务器读取文件规格。结果文字与字词时间轴保留7天，需及时保存；words.type 可能为 word、spacing 或 audio_event，时间为空时不要强行作为字幕词。
统一报价、提交、取结果
POST /api/v1/quotes：正文{"capability":"music.generate","model":"fal-music","input":{"prompt":"安静钢琴背景","duration":8}}。只报价，不生成、不扣点。核对返回estimated_credits, max_credits, price_version, input, expires_at。- 提交前将操作 UUID、完整报价和正文写入当前工程的持久状态文件。
POST /api/v1/generations，带Idempotency-Key: <本次操作UUID>，正文原样使用报价返回的quote_id, capability, model, input, max_credits。max_credits是平台点数；不能填人民币。返回202、task_id, status_url。 GET /api/v1/tasks/{task_id}每2–5秒查询。queued/dispatching/running等待；reconciling保留原操作与任务，等待核对，不能新建收费请求试错。failed/cancelled查看错误与收据，不自动换模型重试。succeeded或partially_succeeded检查result_assets，逐个GET /api/v1/assets/{id}/download带同一用户 Key。支持 Range；重复下载不会重新生成。ASR 从任务的transcription取文字与时间轴，不存在音频输出资产。GET /api/v1/tasks/{id}/receipt核对预占、扣点、释放及版本。下载后的实际文件规格优先于希望生成的规格。- 明确不再需要的私有素材可
DELETE /api/v1/assets/{id}。删除不能撤销已完成生成费用。
提交连接断开时重发同一 UUID、同一正文；收到 task_id 后只查询该任务。不要因响应超时、报价过期、结果暂时为空而换 UUID。已提交任务的重放会先返回原任务。需要制作新的内容、换声或换模型时才创建新的操作，并重新核对预算。
免费音乐及图片、视频素材
授权背景音乐99首，按类型筛选：
GET /api/v1/music/categories：可选类型、情绪、风格与数量。GET /api/v1/search?provider=licensed&kind=music&type=technology&mood=calm&limit=6：参数值以分类接口返回为准；也支持 q、genre、min_duration、max_duration、exclude、page。- 音乐详情及试听地址从搜索响应读取；选用
POST /api/v1/assets/select，正文{"source_ref":"搜索原样返回值","purpose":"local_creation"}，再下载本人资产。 - 图片/视频检索
provider=pexels|pixabay|unsplash, kind=image|video；Unsplash仅图片，下载返回 hotlink JSON，按external_url使用，不能把它当图片二进制。
检索需对应 music.search/images.search/videos.search，选用需 assets.write，下载需 assets.read。保留每条素材的许可、作者与来源，不能用“接口免费”代替授权信息。
TTS 2.0 全部音色
TTS 2.0模型 volc-tts-2.0，正式音色目录 GET /api/v1/tts/voices（公开、0点）。支持q/gender/category/language/page/limit筛选与分页；默认50条、最大100条。items[].id用于报价input.voice，名称、性别、场景、语种及单音色真实验收标志一并返回。2026-10-10接入445个官方公共音色及1个已验收兼容ID。不能将模型ready解读为全部音色已逐一实测。新增可选input.explicit_language与input.enable_auto_language_recognition，旧调用保持兼容。详细说明见高品质配音2.0。本机2.0专用配置为 /Users/michael/.config/motiongit/tts-premium.env，旧tts.env仅1.0；Key不打包进.motion。