[video] fal.ai video generation
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức phù hợp với người mới
- 22/100
Hướng nghiên cứu
Start with the VideoProvider interface and the TypeScript fal entry in src/praisonai-ts/src/llm/providers/ai-sdk/types.ts, then design the new praisonaiagents/video/adapters/fal.py and fal_models.yaml. Several endpoints are still marked TBD, so verify them on fal.ai first. Done means the three fal routes submit, poll and download through mocked queue responses, and LTX rejects durations under 6 seconds.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
Epic: #5171
Problem statement
fal.ai routes in the Video Model Cost Picker:
| Route | Picker detail |
|---|---|
| MiniMax H3 Max (free tier) | 5 gens / 24h @ 480p/768p; verify API vs web-only free tier |
| LTX-2.3 Fast | CHEAP; minimum 6 seconds |
| Gemini Omni Flash 1.1 | Also on Gemini API; first+last frame; TOP RANKED |
PraisonAI TypeScript provider registry (src/praisonai-ts/src/llm/providers/ai-sdk/types.ts):
fal: { package: '@ai-sdk/fal', envKey: 'FAL_KEY', modalities: IMAGE_GEN, ... }
luma: { ..., description: 'Luma AI video generation' } // not wired to Python VideoAgent
Python VideoAgent has zero fal video code.
fal.ai integration pattern
fal models typically use queue API:
POST https://queue.fal.run/{model_id}or REST from model page- Receive
request_id - Poll
GET .../requests/{request_id}/statusor use client SDK - Read
response.video.url(field names vary by model)
Do not assume one JSON schema. Implement endpoint map:
# praisonaiagents/video/fal_models.yaml
ltx-2.3-fast:
endpoint: "fal-ai/ltx-video-2.3-fast" # verify on fal.ai at implement time
min_duration: 6
default_resolution: "720p"
minimax-h3-max:
endpoint: "..."
experimental_free_tier: true
gemini-omni-flash-11:
endpoint: "..."
supports_first_last_frame: true
Authentication
Authorization: Key $FAL_KEY
Or header format per fal docs (Authorization: Bearer ... — confirm current fal spec in PR).
Env: FAL_KEY (match TS envKey).
FalVideoProvider implementation
File: praisonaiagents/video/adapters/fal.py
class FalVideoProvider(VideoProvider):
provider_id = "fal"
def generate(...) -> VideoJob:
model_id = self._strip_prefix(model) # fal/ltx-2.3-fast -> config key
cfg = self._load_model_config(model_id)
self._validate_duration(seconds, cfg.min_duration)
payload = self._build_payload(prompt, seconds, size, input_reference, kwargs, cfg)
request_id = self._submit(cfg.endpoint, payload)
return VideoJob(id=f"fal:{request_id}", status="pending", ...)
def get_status(...): ...
def download(...): ...
LTX-2.3 Fast validation
if int(seconds) < 6:
raise VideoProviderValidationError(
"LTX-2.3 Fast requires duration >= 6 seconds (cost picker minimum)"
)
MiniMax H3 Max
- Example README blockquote: verify whether API calls consume free tier
- Optional env gate:
FAL_CONFIRM_PAID_USAGE=1before submit
Gemini Omni Flash 1.1 (fal path)
Map:
input_reference→ first frame image (URL/base64/upload)last_framekwarg → second frame- Document overlap with native Gemini video APIs to avoid double documentation (#10)
Model naming
VideoAgent(llm="fal/ltx-2.3-fast")
VideoAgent(llm="fal/minimax-h3-max")
VideoAgent(llm="fal/gemini-omni-flash-1.1")
Registry prefix fal/.
Async / long-running jobs
fal jobs may exceed VideoConfig.timeout (default 600s). Allow:
VideoConfig.max_wait_timeup to 3600 for slow queues- Progress logging in
wait_for_completion
Testing
Mock queue responses:
- submit →
{ "request_id": "..." } - status
IN_PROGRESS→COMPLETED - completed payload with
{ "video": { "url": "https://..." } }
Tests:
- LTX rejects
seconds=5 - Omni builds two-frame payload
- Missing
FAL_KEY→ auth error
Examples
examples/python/video/video_fal_ltx23.py— duration=6, resolution from pickerexamples/python/video/video_fal_minimax_h3.py— billing warning headerexamples/python/video/video_fal_omni_flash.py— two-frame I2V
Acceptance criteria
- Three fal picker routes implemented (config-driven)
- fal YAML config validated in CI (schema check)
- Registry + CLI + MCP integration
- Matrix rows with fal channel marked Supported
Dependencies
Requires #02
Related
Epic #01, #08, #10
References
- https://fal.ai/models
- Cost picker artifact
Appendix: fal model config schema
models:
ltx-2.3-fast:
endpoint: fal-ai/ltx-video-2.3-fast
min_duration: 6
minimax-h3-max:
endpoint: TBD
free_tier_unverified: true
gemini-omni-flash-1.1:
endpoint: TBD
two_frame: true
Appendix: Validation rules
- Rule 1: validate payload keys against YAML before HTTP
- Rule 2: validate payload keys against YAML before HTTP
- Rule 3: validate payload keys against YAML before HTTP
- Rule 4: validate payload keys against YAML before HTTP
- Rule 5: validate payload keys against YAML before HTTP
- Rule 6: validate payload keys against YAML before HTTP
- Rule 7: validate payload keys against YAML before HTTP
- Rule 8: validate payload keys against YAML before HTTP
- Rule 9: validate payload keys against YAML before HTTP
- Rule 10: validate payload keys against YAML before HTTP
- Rule 11: validate payload keys against YAML before HTTP
- Rule 12: validate payload keys against YAML before HTTP
- Rule 13: validate payload keys against YAML before HTTP
- Rule 14: validate payload keys against YAML before HTTP
- Rule 15: validate payload keys against YAML before HTTP
- Rule 16: validate payload keys against YAML before HTTP
- Rule 17: validate payload keys against YAML before HTTP
- Rule 18: validate payload keys against YAML before HTTP
- Rule 19: validate payload keys against YAML before HTTP
- Rule 20: validate payload keys against YAML before HTTP
- Rule 21: validate payload keys against YAML before HTTP
- Rule 22: validate payload keys against YAML before HTTP
- Rule 23: validate payload keys against YAML before HTTP
- Rule 24: validate payload keys against YAML before HTTP
- Rule 25: validate payload keys against YAML before HTTP
- Rule 26: validate payload keys against YAML before HTTP
- Rule 27: validate payload keys against YAML before HTTP
- Rule 28: validate payload keys against YAML before HTTP
fal queue lifecycle
- POST queue endpoint with model id and input dict (see fal_models.yaml profile).
- Receive
request_idand queue position; namespaced job idfal:{request_id}. - Poll status URL until COMPLETED or FAILED (map to internal terminal set).
- Download result URL from response; validate host against fal.media allowlist (#02 SSRF).
- LTX profiles: enforce minimum 6s duration in validator before submit.
- Omni two-frame: require input_reference; last_frame optional per profile.
- Handle 422 validation errors — surface fal message text to agent user.
- Async path mirrors sync with httpx.AsyncClient for agenerate.
fal integration tests (enumeration)
| Test id | Scenario | Fixture | Expected |
|---|---|---|---|
test_fal_01 |
Scenario 1 | mock HTTP | pass |
test_fal_02 |
Scenario 2 | mock HTTP | pass |
test_fal_03 |
Scenario 3 | mock HTTP | pass |
test_fal_04 |
Scenario 4 | mock HTTP | pass |
test_fal_05 |
Scenario 5 | mock HTTP | pass |
test_fal_06 |
Scenario 6 | mock HTTP | pass |
test_fal_07 |
Scenario 7 | mock HTTP | pass |
test_fal_08 |
Scenario 8 | mock HTTP | pass |
test_fal_09 |
Scenario 9 | mock HTTP | pass |
test_fal_10 |
Scenario 10 | mock HTTP | pass |
test_fal_11 |
Scenario 11 | mock HTTP | pass |
test_fal_12 |
Scenario 12 | mock HTTP | pass |
test_fal_13 |
Scenario 13 | mock HTTP | pass |
test_fal_14 |
Scenario 14 | mock HTTP | pass |
test_fal_15 |
Scenario 15 | mock HTTP | pass |
test_fal_16 |
Scenario 16 | mock HTTP | pass |
test_fal_17 |
Scenario 17 | mock HTTP | pass |
test_fal_18 |
Scenario 18 | mock HTTP | pass |
test_fal_19 |
Scenario 19 | mock HTTP | pass |
test_fal_20 |
Scenario 20 | mock HTTP | pass |
test_fal_21 |
Scenario 21 | mock HTTP | pass |
test_fal_22 |
Scenario 22 | mock HTTP | pass |
test_fal_23 |
Scenario 23 | mock HTTP | pass |
test_fal_24 |
Scenario 24 | mock HTTP | pass |
test_fal_25 |
Scenario 25 | mock HTTP | pass |
test_fal_26 |
Scenario 26 | mock HTTP | pass |
test_fal_27 |
Scenario 27 | mock HTTP | pass |
test_fal_28 |
Scenario 28 | mock HTTP | pass |
Billing verification checklist
- Confirm
FAL_KEYscoped to project with video models enabled. - Catalog row
pricing.mode=per_secondmatches fal published rates within 1%. - Log
usageor billed seconds when API returns them for #08 reconciliation. - Alert if daily spend exceeds threshold (external — document hook point in provider).
- Test refund/failure path — failed jobs must not increment success metrics.
- Document that fal queue time is not billable unless provider charges queue fee.
- Compare estimator vs one live 5s LTX clip monthly in staging.
- Ensure failed downloads do not retry infinitely (cap at 3).
- Verify USD display uses Decimal in #08 not float accumulation.
- Add fal model id to SUPPORT_MATRIX with
implementation_status=supported.
Additional verification notes
- Ngôn ngữ chính
- Python
- Star
- 9.3k
- Fork
- 1.5k
- Merge trung bình
- 1 ngày 5 giờ
- Pull request đã merge (30 ngày)
- 520
Chuẩn bị môi trường
Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của MervinPraison/PraisonAI
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
MervinPraison/PraisonAI#6710 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
claude
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 74/100
MervinPraison/PraisonAI#6707 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug claude
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
MervinPraison/PraisonAI#6671 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Compaction budget regression fixture remains below budget with accurate tokenizationCó thể làm lại được Pull request cho issue này đã bị đóng mà không được merge. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 62/100
MervinPraison/PraisonAI#5418 · 3 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug claude documentation
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
MervinPraison/PraisonAI#5341 · 3 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của MervinPraison/PraisonAI
Issue tương tự
-
cognition
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
Maintainer thường phản hồi trong vòng 1 ngày
-
[Suggestion]: Geonode MCP ServerĐang mở
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 78/100
collabnix/awesome-mcp-lists#433 ·
Maintainer thường phản hồi trong vòng 4 ngày
-
CrossEntropyFilter raises on zero probabilities and single-class resultsCó thể đã có người làm @NopeCharon đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
datajoint/datajoint-python#1703 ·
Maintainer thường phản hồi trong vòng 6 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Archmonger/ServeStatic#129 ·