Fliz API 集成技能

以编程方式将文本内容转换为 AI 生成的视频。

快速参考

认证

所有请求均需使用 Bearer Token 进行身份验证：

curl -X GET "https://app.fliz.ai/api/rest/voices" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json"

调用 GET /api/rest/voices 测试连接——若 Token 有效，将返回 HTTP 200 状态码。

核心接口

1. 创建视频

POST /api/rest/video

最简请求示例：

{
  "fliz_video_create_input": {
    "name": "视频标题",
    "description": "需转换为视频的完整文本内容",
    "format": "size_16_9",
    "lang": "en"
  }
}

响应示例：

{
  "fliz_video_create": {
    "video_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
}

重要提示：description 字段必须包含完整的纯文本内容。Fliz 不支持从 URL 中自动提取内容——上游系统需自行完成内容抓取与预处理。

2. 查询视频状态

GET /api/rest/videos/{id}

轮询该接口以跟踪视频生成进度。重点关注 step 字段：

3. 列出视频

GET /api/rest/videos?limit=20&offset=0

4. 视频翻译

POST /api/rest/videos/{from_video_id}/translate?new_lang=fr

在目标语言下创建一个新视频。

5. 复制视频

POST /api/rest/videos/{from_video_id}/duplicate

6. 列出可用音色 / 背景音乐

GET /api/rest/voices
GET /api/rest/musics

视频创建参数

必填字段

• name（字符串）：视频标题
• description（字符串）：完整文本内容
• format（枚举）：size_16_9 | size_9_16 | square
• lang（字符串）：ISO 639-1 语言代码（如 en、fr、es、de、pt 等）

可选自定义参数

注意：当 category 设为 product 或 ad 时，image_urls 为必填项，且需提供 3–10 张图片。

完整枚举值列表详见 references/enums-values.md。

Webhook 回调

配置 webhook_url 参数，即可在视频生成完成或失败时接收事件通知：

{
  "event": "video.complete",
  "video_id": "a1b2c3d4-...",
  "step": "complete",
  "url": "https://cdn.fliz.ai/videos/xxx.mp4"
}

错误处理

集成模式

轮询模式（推荐）

1. POST /api/rest/video → 获取 video_id
2. 循环调用 GET /api/rest/videos/{id}
   - 若 step == "complete"：任务完成，提取 url 字段
   - 若 step 包含 "failed"：发生错误，检查 error 字段
   - 否则：等待 10–30 秒后重试

Webhook 模式

1. POST /api/rest/video 并携带 webhook_url 参数
2. 收到 Webhook 回调后执行业务逻辑处理

代码示例

参见 assets/examples/ 目录下的开箱即用实现：

• python_client.py — 完整 Python 封装类
• nodejs_client.js — Node.js 实现版本
• curl_examples.sh — cURL 命令集合
• webhook_handler.py — 基于 Flask 的 Webhook 服务端示例

脚本工具

运行方式：python scripts/