Fliz API Integration Skill
Transform text content into AI-generated videos programmatically.
Quick Reference
Item Value Base URL INLINECODE0 Auth
Bearer Token (JWT) |
| Get Token | https://app.fliz.ai/api-keys |
| API Docs | https://app.fliz.ai/api-docs |
| Format | JSON |
Authentication
All requests require Bearer token authentication:
CODEBLOCK0
Test connection by calling GET /api/rest/voices - returns 200 if token is valid.
Core Endpoints
1. Create Video
CODEBLOCK1
Minimal request:
Response:
CRITICAL : The description field must contain the FULL TEXT content. Fliz does NOT extract content from URLs - upstream systems must fetch/process content first.
2. Get Video Status
CODEBLOCK4
Poll this endpoint to track video generation progress. Check the step field:
Step Status INLINECODE4 → scrapping → script → image_* → speech → INLINECODE9 Processing INLINECODE10
✅ Ready -
url field contains MP4 |
|
failed /
failed_unrecoverable | ❌ Error - check
error field |
|
user_action | ⚠️ Requires manual intervention |
3. List Videos
CODEBLOCK5
4. Translate Video
CODEBLOCK6
Creates a new video in the target language.
5. Duplicate Video
CODEBLOCK7
6. List Voices / Musics
CODEBLOCK8
Video Creation Parameters
Required Fields
- name (string): Video title INLINECODE17 (string): Full text content INLINECODE18 (enum): size_16_9 | size_9_16 | INLINECODE21 INLINECODE22 (string): ISO 639-1 code (en, fr, es, de, pt, etc.) Optional Customization
Field Description Default INLINECODE23 INLINECODE24 \ INLINECODE25 \ INLINECODE26 INLINECODE27 INLINECODE28
Narrative style | auto |
|
image_style | Visual style |
hyperrealistic |
|
caption_style | Subtitle style |
animated_background |
|
caption_position |
bottom \|
center |
bottom |
|
caption_font | Font family |
poppins |
|
caption_color | Hex color (#FFFFFF) | white |
|
caption_uppercase | Boolean | false |
|
voice_id | Custom voice ID | auto |
|
is_male_voice | Boolean | auto |
|
music_id | Music track ID | auto |
|
music_url | Custom music URL | null |
|
music_volume | 0-100 | 15 |
|
watermark_url | Image URL | null |
|
site_url | CTA URL | null |
|
site_name | CTA text | null |
|
webhook_url | Callback URL | null |
|
is_automatic | Auto-process | true |
|
video_animation_mode |
full_video \|
hook_only |
full_video |
|
image_urls | Array of URLs | null |
Note : For product and ad categories, image_urls is required (3-10 images).
For complete enum values, see references/enums-values.md .
Webhooks
Configure webhook_url to receive notifications when video is ready or fails:
CODEBLOCK9
Error Handling
HTTP Code Meaning Action 200 Success Continue 400
Bad Request | Check params |
| 401 | Unauthorized | Invalid/expired token |
| 404 | Not Found | Invalid video ID |
| 429 | Rate Limited | Retry with backoff |
| 500 | Server Error | Retry later |
Integration Patterns
Polling Pattern (Recommended)
CODEBLOCK10
Webhook Pattern
CODEBLOCK11
Code Examples
See assets/examples/ for ready-to-use implementations:
- python_client.py - Full Python wrapper INLINECODE61 - Node.js implementation INLINECODE62 - cURL commands INLINECODE63 - Flask webhook server Scripts
Script Usage INLINECODE64 Validate API key INLINECODE65
Create video from text file |
|
scripts/poll_status.py | Monitor video generation |
|
scripts/list_resources.py | Fetch voices/musics |
Run with: INLINECODE68
Common Issues
"Invalid API response" : Verify JSON structure matches documentation exactly.
Video stuck in processing : Check step field - some steps like user_action require manual intervention in Fliz dashboard.
No URL extraction : The API requires direct text input. Build content extraction into your integration.
References
Fliz API 集成技能
以编程方式将文本内容转化为AI生成的视频。
快速参考
项目 值 基础URL https://app.fliz.ai 认证方式
Bearer令牌（JWT） |
| 获取令牌 | https://app.fliz.ai/api-keys |
| API文档 | https://app.fliz.ai/api-docs |
| 格式 | JSON |
认证
所有请求都需要Bearer令牌认证：
bashAPI KEY \
通过调用 GET /api/rest/voices 测试连接——如果令牌有效则返回200。
核心端点
1. 创建视频
POST /api/rest/video
最小请求： video create_input: {16 9,
响应： video create: {
关键提示 ：description字段必须包含完整文本 内容。Fliz不会从URL提取内容——上游系统必须首先获取/处理内容。
2. 获取视频状态
GET /api/rest/videos/{id}
轮询此端点以跟踪视频生成进度。检查step字段：
步骤 状态 pending → scrapping → script → image* → speech → video rendering 处理中 complete
✅ 就绪 - url字段包含MP4 |
| failed / failed_unrecoverable | ❌ 错误 - 检查error字段 |
| user_action | ⚠️ 需要手动干预 |
3. 列出视频
GET /api/rest/videos?limit=20&offset=0
4. 翻译视频
POST /api/rest/videos/{fromvideo id}/translate?new_lang=fr
创建目标语言的新视频。
5. 复制视频
POST /api/rest/videos/{fromvideo id}/duplicate
6. 列出语音/音乐
GET /api/rest/voices
视频创建参数
必填字段
- name（字符串）：视频标题 description（字符串）：完整文本内容 format（枚举）：size16 9 | size9 16 | square lang（字符串）：ISO 639-1代码（en、fr、es、de、pt等） 可选自定义
字段 描述 默认值 category article \ product \ ad article script_style
叙述风格 | auto |
| image_style | 视觉风格 | hyperrealistic |
| caption
style | 字幕风格 | animated background |
| caption_position | bottom \| center | bottom |
| caption_font | 字体族 | poppins |
| caption_color | 十六进制颜色（#FFFFFF） | 白色 |
| caption_uppercase | 布尔值 | false |
| voice_id | 自定义语音ID | auto |
| is
male voice | 布尔值 | auto |
| music_id | 音乐曲目ID | auto |
| music_url | 自定义音乐URL | null |
| music_volume | 0-100 | 15 |
| watermark_url | 图片URL | null |
| site_url | CTA URL | null |
| site_name | CTA文本 | null |
| webhook_url | 回调URL | null |
| is_automatic | 自动处理 | true |
| video
animation mode | full
video \| hook only | full_video |
| image_urls | URL数组 | null |
注意 ：对于product和ad类别，image_urls为必填（3-10张图片）。
完整枚举值请参见 references/enums-values.md 。
Webhooks
配置webhook_url以在视频就绪或失败时接收通知：
json
错误处理
错误请求 | 检查参数 |
| 401 | 未授权 | 令牌无效/过期 |
| 404 | 未找到 | 视频ID无效 |
| 429 | 速率限制 | 退避重试 |
| 500 | 服务器错误 | 稍后重试 |
集成模式
轮询模式（推荐）
1. POST /api/rest/video → 获取video_id 循环：GET /api/rest/videos/{id}
- 如果step == complete：完成，获取url
- 如果step包含failed：错误
- 否则：等待10-30秒，重试
Webhook模式
1. 使用webhook_url调用POST /api/rest/video 收到webhook回调时进行处理 代码示例
参见 assets/examples/ 获取可直接使用的实现：
- pythonclient.py - 完整Python封装 nodejsclient.js - Node.js实现 curlexamples.sh - cURL命令 webhookhandler.py - Flask webhook服务器 脚本
脚本 用途 scripts/testconnection.py 验证API密钥 scripts/createvideo.py
从文本文件创建视频 |
| scripts/poll_status.py | 监控视频生成 |
| scripts/list_resources.py | 获取语音/音乐 |
运行方式：python scripts/
