modbender Fliz API Integration Skill
Transform text content into AI-generated videos programmatically.
Quick Reference
| Item | Value |
|---|---|
| Base URL | https://app.fliz.ai |
| 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:
curl -X GET "https://app.fliz.ai/api/rest/voices" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
Test connection by calling GET /api/rest/voices - returns 200 if token is valid.
Core Endpoints
1. Create Video
POST /api/rest/video
Minimal request:
{
"fliz_video_create_input": {
"name": "Video Title",
"description": "Full content text to transform into video",
"format": "size_16_9",
"lang": "en"
}
}
Response:
{
"fliz_video_create": {
"video_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}
}
CRITICAL: The
descriptionfield must contain the FULL TEXT content. Fliz does NOT extract content from URLs - upstream systems must fetch/process content first.
2. Get Video Status
GET /api/rest/videos/{id}
Poll this endpoint to track video generation progress. Check the step field:
| Step | Status |
|---|---|
pending → scrapping → script → image_* → speech → video_rendering |
Processing |
complete |
✅ Ready - url field contains MP4 |
failed / failed_unrecoverable |
❌ Error - check error field |
user_action |
⚠️ Requires manual intervention |
3. List Videos
GET /api/rest/videos?limit=20&offset=0
4. Translate Video
POST /api/rest/videos/{from_video_id}/translate?new_lang=fr
Creates a new video in the target language.
5. Duplicate Video
POST /api/rest/videos/{from_video_id}/duplicate
6. List Voices / Musics
GET /api/rest/voices
GET /api/rest/musics
Video Creation Parameters
Required Fields
name(string): Video titledescription(string): Full text contentformat(enum):size_16_9|size_9_16|squarelang(string): ISO 639-1 code (en, fr, es, de, pt, etc.)
Optional Customization
| Field | Description | Default |
|---|---|---|
category |
article | product | ad |
article |
script_style |
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
productandadcategories,image_urlsis 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:
{
"event": "video.complete",
"video_id": "a1b2c3d4-...",
"step": "complete",
"url": "https://cdn.fliz.ai/videos/xxx.mp4"
}
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)
1. POST /api/rest/video → get video_id
2. Loop: GET /api/rest/videos/{id}
- If step == "complete": done, get url
- If step contains "failed": error
- Else: wait 10-30s, retry
Webhook Pattern
1. POST /api/rest/video with webhook_url
2. Process webhook callback when received
Code Examples
See assets/examples/ for ready-to-use implementations:
python_client.py- Full Python wrappernodejs_client.js- Node.js implementationcurl_examples.sh- cURL commandswebhook_handler.py- Flask webhook server
Scripts
| Script | Usage |
|---|---|
scripts/test_connection.py |
Validate API key |
scripts/create_video.py |
Create video from text file |
scripts/poll_status.py |
Monitor video generation |
scripts/list_resources.py |
Fetch voices/musics |
Run with: python scripts/<script>.py --api-key YOUR_KEY
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
- API Reference - Complete endpoint documentation
- Enum Values - All valid parameter values
- Integration Examples - Ready-to-use code