# @554/video > End-to-end video generation via fal.ai through Starchild paid proxy. Covers text-to-video, image-to-video, video-to-video, model selection, billing, polling, and serving local reference assets via a public preview. - Skill: `starchild-ai-agent/554-video` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add starchild-ai-agent/554-video` - Raw SKILL.md: https://api.skillmd.com/api/skills/starchild-ai-agent/554-video/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: starchild-ai-agent (https://skillmd.com/u/starchild-ai-agent) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/starchild-ai-agent/554-video --- # video Use this skill for **all video-generation requests** on Starchild. **Core principle:** call the provided scripts. Do not re-implement proxy/billing/upload plumbing. --- ## 1. Text-to-video (most common) ```python exec(open('skills/video/generate_video.py').read()) result = generate_video( prompt="A cinematic drone shot over snowy mountains at sunrise", model="balanced", # "budget" | "balanced" | "premium" duration=5, ) # result -> {"success": True, "cost": 0.70, "video_url": "...", "local_path": "output/videos/..."} ``` `generate_video` automatically: submits → polls → fetches result → downloads mp4 to `output/videos/`. --- ## 2. Image-to-video / video-to-video (reference assets) fal.ai needs the reference asset as a **public https URL**. fal storage upload requires a Serverless permission your key currently does not have. The reliable path is to expose the asset via **a published Starchild preview**. ### Standard procedure 1. **Drop or copy the asset** into `output/fal_assets/` using `publish_asset.py`. 2. **Make sure a preview named `fal-assets` is running and published** (one-time setup, see §3). 3. **Build the public URL** as `/`. 4. **Call `generate_video(... image_url=public_url)`**. ```python # Step 1: publish a local image into the asset folder exec(open('skills/video/publish_asset.py').read()) asset = publish_local('/path/to/your/photo.jpg') # or: publish_from_url('https://example.com/photo.jpg') filename = asset['filename'] # Step 2: combine with the preview's public base URL (see §3) public_url = f"https://community.iamstarchild.com/-fal-assets/{filename}" # Step 3: image-to-video exec(open('skills/video/generate_video.py').read()) result = generate_video( prompt="gentle cinematic camera push-in", model="balanced", duration=5, image_url=public_url, ) ``` `generate_video` auto-rewrites the model path from `*/text-to-video` to `*/image-to-video` whenever `image_url` is provided. The same approach works for video-to-video models — pass an mp4 URL instead. ### Asset constraints (enforced by `publish_asset.py`) - Image: `.jpg .jpeg .png .webp .gif .bmp`, max **10 MB** - Video: `.mp4 .mov .webm .mkv .m4v`, max **100 MB** - Anything outside these is rejected before publish --- ## 3. One-time `fal-assets` public preview setup Run this once per workspace. The preview keeps running across sessions. ```python # 3.1 ensure the asset folder exists with a placeholder index import os, pathlib pathlib.Path('output/fal_assets').mkdir(parents=True, exist_ok=True) if not os.path.exists('output/fal_assets/index.html'): open('output/fal_assets/index.html', 'w').write( '

fal asset host

' ) # 3.2 start the preview preview(action='serve', dir='output/fal_assets', title='fal-assets') # 3.3 publish to a public URL preview(action='publish', preview_id='', slug='fal-assets', title='fal-assets') # → public base: https://community.iamstarchild.com/-fal-assets/ ``` After publish, the public base URL is reusable for every future image-to-video / video-to-video task. Files dropped into `output/fal_assets/` become reachable as `/` immediately — no re-publish needed. Verify with: ```bash curl -sI https://community.iamstarchild.com/-fal-assets/ # expect: HTTP/2 200, content-type: image/* or video/* ``` If `preview(action='serve')` returns `No available ports in pool`, ask the user which existing preview can be stopped to free a port — never silently kill one. --- ## 4. Model selection | Tier | Model | Cost / 5s | Notes | |------|-------|-----------|-------| | **budget** | `fal-ai/wan/v2.5/text-to-video` | $0.25 | Fastest, cheapest; good for prompt iteration | | **balanced** | `alibaba/happy-horse/text-to-video` | $0.70 | Default; best lip-sync, most use cases | | **premium** | `bytedance/seedance-2.0/fast/text-to-video` | $1.20 | Best motion + camera direction | Override by passing the full model id to `generate_video(model=...)`. Image-to-video variants are auto-derived by replacing `text-to-video` with `image-to-video`. Pricing details and model registry live in `generate_video.py::estimate_cost`. --- ## 5. Polling an existing request ```python exec(open('skills/video/poll_status.py').read()) result = poll_video("019ded6c-d871-7290-bbf1-ddc6993f8958") ``` Use this when an earlier `generate_video` call timed out or you only have a `request_id`. --- ## 6. Provided scripts - `generate_video.py` — submit → poll → download. Handles text-to-video and image-to-video. - `publish_asset.py` — copy local files (or download remote URLs) into `output/fal_assets/` so they can be served by the `fal-assets` preview. - `poll_status.py` — resume polling by `request_id`, downloads the result on completion. --- ## 7. Troubleshooting | Problem | Fix | |---------|-----| | `image_url must be a public HTTP(S) URL` | Use `publish_asset.py` + `fal-assets` preview, then pass the public URL | | `No available ports in pool` (preview serve) | Ask the user which preview to stop; do not auto-kill | | `downstream_service_error` after `COMPLETED` | Reference asset host failed mid-render — re-encode/resize to 16:9, re-publish, retry | | `HTTP 402 insufficient_credits` | Top up balance; cost is pre-charged on submit | | `HTTP 403 endpoint_not_allowed` | sc-proxy only allows approved fal video endpoints; pick one from the model table | | Generation `FAILED` upstream | Shorten prompt, drop unusual tokens, retry once before changing model | | Job stuck `IN_PROGRESS` >15 min | Save `request_id`, resume later with `poll_status.py` | --- ## 8. Infrastructure (reference) - Caller → `sc-proxy` → `queue.fal.run` (and `api.fal.ai`) → fal model providers - All requests must include `Authorization: Key fake-falai-key-12345` (proxy injects the real `FAL_KEY`) - Pre-charge happens at submit. Poll/result calls are free. - Allowed endpoints: video text-to-video / image-to-video / video-to-video / edit-video for the registered models. Anything else returns `403 endpoint_not_allowed`. - Final mp4 lives at `https://*.fal.media/...` — public CDN, no auth needed for download. --- ## 9. Maintenance - Adding a new model → register price in `generate_video.py::estimate_cost` and in `transparent-proxy/apis/falai.py::_VIDEO_PRICING`. - Asset hosting via fal storage upload is intentionally **not** used in this skill: the production `FAL_KEY` lacks Serverless permission. Keep using the preview-based approach until that changes.