| name | @554/video |
| version | 3.0.0 |
| description | 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. |
| metadata | {"starchild":{"emoji":"🎬","skillKey":"video","requires":{"env":["FAL_KEY"]}}} |
| user-invocable | true |
| disable-model-invocation | false |
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)
exec(open('skills/video/generate_video.py').read())
result = generate_video(
prompt="A cinematic drone shot over snowy mountains at sunrise",
model="balanced",
duration=5,
)
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
- Drop or copy the asset into
output/fal_assets/ using publish_asset.py.
- Make sure a preview named
fal-assets is running and published (one-time setup, see §3).
- Build the public URL as
<preview_base>/<filename>.
- Call
generate_video(... image_url=public_url).
exec(open('skills/video/publish_asset.py').read())
asset = publish_local('/path/to/your/photo.jpg')
filename = asset['filename']
public_url = f"https://community.iamstarchild.com/<user_slug>-fal-assets/{filename}"
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.
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(
'<!doctype html><html><body><h1>fal asset host</h1></body></html>'
)
preview(action='serve', dir='output/fal_assets', title='fal-assets')
preview(action='publish', preview_id='<id from step 3.2>', slug='fal-assets', title='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 <base>/<filename> immediately — no re-publish needed.
Verify with:
curl -sI https://community.iamstarchild.com/<user_slug>-fal-assets/<filename>
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
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.
