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:
CODEBLOCK2
Response:
CODEBLOCK3
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令牌认证：
bash
curl -X GET https://app.fliz.ai/api/rest/voices \
-H Authorization: Bearer YOURAPIKEY \
-H Content-Type: application/json
通过调用 GET /api/rest/voices 测试连接——如果令牌有效则返回200。
核心端点
1. 创建视频
POST /api/rest/video
最小请求：
json
{
flizvideocreate_input: {
name: 视频标题,
description: 要转化为视频的完整文本内容,
format: size169,
lang: en
}
}
响应：
json
{
flizvideocreate: {
video_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
}
}
关键提示：description字段必须包含完整文本内容。Fliz不会从URL提取内容——上游系统必须首先获取/处理内容。
2. 获取视频状态
GET /api/rest/videos/{id}
轮询此端点以跟踪视频生成进度。检查step字段：
| 步骤 | 状态 |
|---|
| pending → scrapping → script → image* → speech → videorendering | 处理中 |
| complete |
✅ 就绪 - url字段包含MP4 |
| failed / failed_unrecoverable | ❌ 错误 - 检查error字段 |
| user_action | ⚠️ 需要手动干预 |
3. 列出视频
GET /api/rest/videos?limit=20&offset=0
4. 翻译视频
POST /api/rest/videos/{fromvideoid}/translate?new_lang=fr
创建目标语言的新视频。
5. 复制视频
POST /api/rest/videos/{fromvideoid}/duplicate
6. 列出语音/音乐
GET /api/rest/voices
GET /api/rest/musics
视频创建参数
必填字段
- - name（字符串）：视频标题
- description（字符串）：完整文本内容
- format（枚举）：size169 | size916 | square
- lang（字符串）：ISO 639-1代码（en、fr、es、de、pt等）
可选自定义
| 字段 | 描述 | 默认值 |
|---|
| category | article \ | product \ | ad | article |
| script_style |
叙述风格 | auto |
| image_style | 视觉风格 | hyperrealistic |
| caption
style | 字幕风格 | animatedbackground |
| caption_position | bottom \| center | bottom |
| caption_font | 字体族 | poppins |
| caption_color | 十六进制颜色（#FFFFFF） | 白色 |
| caption_uppercase | 布尔值 | false |
| voice_id | 自定义语音ID | auto |
| is
malevoice | 布尔值 | 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
animationmode | full
video \| hookonly | full_video |
| image_urls | URL数组 | null |
注意：对于product和ad类别，image_urls为必填（3-10张图片）。
完整枚举值请参见 references/enums-values.md。
Webhooks
配置webhook_url以在视频就绪或失败时接收通知：
json
{
event: video.complete,
video_id: a1b2c3d4-...,
step: complete,
url: https://cdn.fliz.ai/videos/xxx.mp4
}
错误处理
错误请求 | 检查参数 |
| 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/
