常见问题（FAQ）

如何获取 API Key？

联系平台管理员开通账号，管理员会为您分配一个主密钥（app-key）。获取后，在所有 API 请求的 Header 中携带即可：

app-key: your_app_key_here

支持哪些文件格式？

文件类型	支持格式
视频	MP4、MOV、MKV
音频	MP3、WAV、M4A
字幕	SRT
图片	JPG、PNG

任务积分是怎么扣费的？

创建任务时系统会根据任务类型扣除对应积分，余额不足时任务将无法创建。各任务类型的计费规则请参考接口文档中的说明。

如何查看积分余额？

通过用户余额接口查询：

返回示例：

{
  "code": 10000,
  "message": "Success",
  "data": {
    "balance": 8500.0
  }
}

回调通知失败怎么办？

如果回调地址不可达或返回非 2xx 状态码，平台不会自动重试回调。建议：

主动轮询 — 定期调用 GET /v1/tasks/{task_id} 查询任务状态

SSE 推送 — 通过 GET /v1/tasks/{task_id}/stream 实时接收任务进度

确保回调地址可用 — 回调地址需为公网可访问的 HTTPS 地址

工作流和单任务有什么区别？

对比项	单任务	工作流
创建方式	`POST /v1/tasks/{type}`	`POST /v1/workflows/execute`
执行范围	单个任务独立执行	多个任务按顺序自动串联
适用场景	单一功能调用（如 TTS、字幕擦除）	完整视频制作流程（如解说视频从学习到合成）
计费方式	单任务独立计费	工作流内各步骤分别计费
结果获取	查询单个 task_id	查询 execution_id 获取整体进度和各步骤状态

可用工作流

工作流名称	说明	步骤
`viral_narration`	二创解说视频	爆款学习 → 解说文案 → 剪辑数据 → 视频合成 → 视觉模板（可选）

工作流费用预估

执行前可先预估总费用：

如何获取配音音色列表？

通过配音音色资源接口获取：

返回包含所有可用音色的列表，每个音色包含 voice_id、name、language、demo_url 等信息。创建 TTS 任务时使用 voice_id 参数指定音色。

其他资源列表接口：

接口	说明
`GET /v1/resources/voices`	配音音色列表
`GET /v1/resources/bgm`	BGM 背景音乐列表
`GET /v1/resources/templates`	解说模板列表
`GET /v1/resources/visual-templates`	视觉模板列表
`GET /v1/resources/clips`	素材片段列表
`GET /v1/resources/languages`	支持语言列表
`GET /v1/resources/writing-types`	文案类型列表
`GET /v1/resources/narrator-types`	解说类型列表

任务最大处理时长是多少？

不同任务类型的处理时长不同，主要受素材时长和任务复杂度影响：

任务类型	典型处理时长	说明
TTS（语音合成）	10 - 60 秒	取决于文本长度
Voice Clone（声音克隆）	1 - 5 分钟	固定处理流程
Viral Learning（爆款学习）	1 - 3 分钟	取决于字幕长度
Generate Writing（解说文案）	1 - 5 分钟	取决于 AI 模型和文案数量
Video Composing（视频合成）	3 - 15 分钟	取决于视频时长和复杂度
Subtitle Removal（字幕擦除）	2 - 10 分钟	取决于视频时长
OCR Extraction（OCR 提取）	1 - 5 分钟	取决于视频时长

以上为参考值，实际处理时长可能因服务器负载和队列情况有所波动。如任务长时间未完成，建议通过任务状态接口确认是否已超时失败。

如何获取 API Key？#

支持哪些文件格式？#

任务积分是怎么扣费的？#

如何查看积分余额？#

回调通知失败怎么办？#

工作流和单任务有什么区别？#

可用工作流#

工作流费用预估#

如何获取配音音色列表？#

任务最大处理时长是多少？#