video

视频

将此技能用于 Starchild 上的所有视频生成请求。

**核心原则：**调用提供的脚本。不要重新实现代理、计费或上传流程。

---

1. 文本生成视频（最常见）

⚠️ 执行环境 — 请先阅读。 下面的代码块是 Python，不是 shell 命令。Starchild 的 bash 工具 运行 /bin/bash -c，无法解析 exec(open(...)) — 直接将它们粘贴到 bash 命令中 会因 syntax error near unexpected token 'open' 而失败。 此外，在 python3 -c 中使用 exec(open(...)) 会因脚本使用 __file__ 进行路径解析 而报错 NameError: __file__。

通过 bash 工具调用时，请使用 python3 - <<'EOF' 和 from exports import：

python3 - <<'EOF'
import sys
sys.path.insert(0, "skills/video")
from generate_video import generate_video
result = generate_video(
    prompt="A cinematic drone shot over snowy mountains at sunrise",
    model="balanced",
    duration=5,
)
print(result)
EOF

heredoc（<<'EOF'）会保留所有引号和换行 — 无需转义。 注意：video 技能没有 exports.py — 请直接从 generate_video 导入。

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 会自动：提交 → 轮询 → 获取结果 → 将 mp4 下载到 output/videos/。

向用户交付结果 — 重要

切勿将原始 video_url（例如 https://*.fal.media/.../*.mp4）直接交给用户。 fal 提供这些文件时会设置 Content-Security-Policy: sandbox; default-src 'none'，这意味着：

• 在浏览器中打开链接会显示空白页面（不会触发内嵌播放器）。
• 通过 <video> / <iframe> 嵌入会被 CSP 阻止。
• 没有 Content-Disposition: attachment 标头，因此浏览器也不会自动下载。
• 修改 URL（查询参数、?download=1 等）无法解决此问题 — 只有服务器端修改标头才能解决，而我们无法控制 fal 的 CDN。

唯一可靠的面向用户的交付方式是使用已下载到本地的文件：

1. 使用 result["local_path"]（例如 output/videos/xxx.mp4）— generate_video 成功时总会下载文件。
2. 告知用户文件已保存到 output/videos/<filename>，可在工作区文件面板 / 文件浏览器中查看。
3. 在 Web 渠道中，还要将视频内嵌，以便用户在聊天中预览：

   ![video](output/videos/<filename>.mp4)
   

   （或者使用 [video](output/videos/<filename>.mp4) 链接 — 工作区会使用正确的标头直接提供这些文件）。
4. 在 Telegram / WeChat 中：通过 send_to_telegram(file_path="output/videos/...", message_type="video") 或 send_to_wechat(file_path="output/videos/...", message_type="video") 发送文件。

如果下载意外失败（缺少 local_path）— 请重新获取：

curl -L -o output/videos/<filename>.mp4 "<video_url>"

然后交付本地路径。仍然不要将原始 fal URL 作为主要交付内容提供给用户。

---

2. 图片生成视频 / 视频生成视频（参考素材）

fal.ai 需要参考素材使用公开的 https URL。fal 存储上传需要 Serverless 权限，而你的密钥目前没有该权限。可靠的方式是通过已发布的 Starchild 预览公开素材。

标准流程

1. 使用 publish_asset.py 将素材放入或复制到 output/fal_assets/。
2. 确保名为 fal-assets 的预览正在运行且已发布（一次性设置，见 §3）。
3. 将公开 URL 构造为 <preview_base>/<filename>。
4. 调用 generate_video(... image_url=public_url)。

# 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/<user_slug>-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,
)

只要提供了 image_url，generate_video 就会自动将模型路径从 */text-to-video 重写为 */image-to-video。同样的方法也适用于视频生成视频模型 — 传入 mp4 URL 即可。

素材限制（由 publish_asset.py 强制执行）

• 图片：.jpg .jpeg .png .webp .gif .bmp，最大 10 MB
• 视频：.mp4 .mov .webm .mkv .m4v，最大 100 MB
• 超出这些限制的文件会在发布前被拒绝

---

3. 一次性 fal-assets 公共预览设置

每个工作区运行一次即可。预览会在不同会话之间持续运行。

# 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(
        '<!doctype html><html><body><h1>fal asset host</h1></body></html>'
    )

# 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='<id from step 3.2>', slug='fal-assets', title='fal-assets')
# → public base: https://community.iamstarchild.com/<user_slug>-fal-assets/

发布后，公共基础 URL 可用于所有后续的图像转视频／视频转视频任务。放入 output/fal_assets/ 的文件会立即通过 <base>/<filename> 访问，无需重新发布。

验证方法：

curl -sI https://community.iamstarchild.com/<user_slug>-fal-assets/<filename>
# expect: HTTP/2 200, content-type: image/* or video/*

如果 preview(action='serve') 返回 No available ports in pool，请询问用户可以停止哪个现有预览来释放端口，切勿擅自终止。

---

4. 模型选择

层级	模型	每 5 秒费用	备注
budget	fal-ai/wan/v2.5/text-to-video	$0.25	速度最快、成本最低；适合迭代提示词
balanced	alibaba/happy-horse/text-to-video	$0.70	默认选项；唇形同步效果最佳，适用于大多数场景
premium	bytedance/seedance-2.0/fast/text-to-video	$1.20	动作和镜头调度效果最佳
mini	bytedance/seedance-2.0/mini/text-to-video	$0.36（480p）／$0.77（720p）	最便宜的 Seedance；按分辨率分档，不支持 1080p。时长必须是字符串（"5"，而不是 5 或 "5s"）——参见下方的注意事项
premium-25	bytedance/seedance-2.5/text-to-video	按 token 计费	支持文本转视频、图像转视频和参考图转视频。需要设置 resolution（480p／720p）、aspect_ratio（支持六种比例）和 4–30 秒的整数 duration。使用 estimate_cost(..., aspect_ratio=...) 估算费用。
—	xai/grok-imagine-video/v1.5/image-to-video	每 5 秒 $0.41（480p）／$0.71（720p）	仅支持图像转视频（必须提供单个 image_url，不支持 image_urls）；估算费用中已包含 $0.01 的输入图像附加费。⚠️ 上游架构允许 resolution="1080p"，但该分辨率没有公开价格——代理会以 400 错误拒绝请求，不会放行
—	fal-ai/kling-video/v3/turbo/standard/text-to-video	每 5 秒 $0.56	Kling v3 Turbo Standard，统一按 $0.112/s 计费；.../turbo/pro/... = $0.14/s（$0.70/5s）；.../v3/4k/... = $0.42/s（$2.10/5s）。所有版本均提供 i2v 变体
—	alibaba/happy-horse/v1.1/text-to-video	每 5 秒 $0.70（720p）／$0.90（1080p）	v1.1 有独立的 1080p 价格档，每秒 $0.18（不适用 v1.0 的 2 倍规则）；还支持 /image-to-video、/reference-to-video
—	fal-ai/minimax_h3/text-to-video	按代理定价	支持文本转视频、图像转视频和参考图转视频。参考图转视频请传入 image_urls=[...]；该字段会被转换为上游的 reference_image_urls。

⚠️ Happy Horse 的默认分辨率在上游为 1080p（v1.0 和 v1.1）：省略 resolution 会按 1080p 档计费（v1.1 每 5 秒 $0.90；v1.0 参考图转视频每 5 秒 $1.40）。请显式传入 resolution="720p"，以使用更低的费率。无效的分辨率值会被代理以 400 错误拒绝。

参考图转视频：传入 image_urls=[...]（包含 1–9 个公开 HTTP(S) URL 的列表），而不是单个 image_url 参数。generate_video() 会验证数量和 URL 方案。Happy Horse 和 Seedance 2.5 会提交 image_urls 字段；MiniMax H3（fal-ai/minimax_h3/reference-to-video）会提交上游的 reference_image_urls 字段。

Seedance 2.5 示例：

result = generate_video(
    prompt="A cinematic close-up of a paper crane unfolding",
    model="bytedance/seedance-2.5/text-to-video",
    duration=5,
    resolution="720p",
    aspect_ratio="16:9",
)

请使用 4–30 秒的整数 duration。resolution 必须是 480p 或 720p；aspect_ratio 必须是 21:9、16:9、4:3、1:1、3:4 或 9:16。代理会拒绝 auto 值，因为无法安全地据此定价。

传入完整模型 ID，即可通过 generate_video(model=...) 覆盖模型。图像转视频变体会通过将 text-to-video 替换为 image-to-video 自动生成。

定价详情和模型注册表位于 generate_video.py::estimate_cost。对于尚未在其中注册的模型，旧版回退估算仅供粗略参考，结果可能与代理不同；请勿用它为新端点制定预算。

---

5. 轮询现有请求

exec(open('skills/video/poll_status.py').read())
result = poll_video("019ded6c-d871-7290-bbf1-ddc6993f8958")

如果先前的 generate_video 调用超时，或你只有 request_id，请使用此方法。

---

6. 提供的脚本

• generate_video.py — 提交 → 轮询 → 下载。支持文生视频和图生视频。
• publish_asset.py — 将本地文件（或远程 URL）复制到 output/fal_assets/，以便通过 fal-assets 预览提供这些文件。
• poll_status.py — 根据 request_id 恢复轮询，并在任务完成后下载结果。

---

7. 故障排查

问题	解决方法
image_url must be a public HTTP(S) URL	使用 publish_asset.py 和 fal-assets 预览，然后传入公开 URL
No available ports in pool（预览服务）	询问用户要停止哪个预览；不要自动结束进程
COMPLETED 后出现 downstream_service_error	引用素材主机在渲染中途发生故障——重新编码/调整尺寸为 16:9，重新发布并重试
HTTP 402 insufficient_credits	充值；提交时会预扣费用
HTTP 403 endpoint_not_allowed	sc-proxy 只允许已批准的 fal 视频端点；从模型表中选择一个
上游生成状态为 FAILED	缩短提示词，移除不常见的词元；更换模型前重试一次
Seedance Mini 的 duration 出现 HTTP 422 literal_error	Mini 要求 duration 为字符串（"5"、"10"、"auto"），不能是整数，也不能是 "5s"。当 model 包含 seedance-2.0/mini 时，generate_video() 会自动按此要求编码——只有手动构造请求体时才会遇到此问题。其他 Seedance 变体仍接受整数或 "5s"。
Seedance 2.5 拒绝 auto，或返回 resolution_not_priceable / aspect_ratio_not_priceable	传入明确的 resolution="480p" 或 "720p"、明确的受支持 aspect_ratio，以及 4–30 之间的整数 duration。Seedance 2.5 按词元计费；调用 estimate_cost(model, duration, resolution, aspect_ratio) 获取本地估算。
MiniMax H3 引用请求返回参数错误	对 fal-ai/minimax_h3/reference-to-video 模型使用 image_urls=[...]。generate_video() 会将其转换为上游的 reference_image_urls；不要向上游手动发送 image_urls。
任务处于 IN_PROGRESS 状态超过 15 分钟	保存 request_id，稍后使用 poll_status.py 恢复轮询
用户报告 fal.media 链接“没有显示内容”／“空白页面”	这是预期行为——fal 使用 CSP: sandbox; default-src 'none' 提供内容。请交付 result["local_path"] 中的本地文件，而不是原始 URL（参见 §1）。

---

8. 基础设施（参考）

• 调用方 → sc-proxy → queue.fal.run（以及 api.fal.ai）→ fal 模型提供商
• 所有请求都必须包含 Authorization: Key fake-falai-key-12345（代理会注入真实的 FAL_KEY）
• 提交时会预扣费用。轮询/结果请求免费。
• 允许的端点：已注册模型的视频文生视频／图生视频／视频转视频／视频编辑。其他请求都会返回 403 endpoint_not_allowed。
• 最终 mp4 文件位于 https://*.fal.media/...——这是公开 CDN，下载无需身份验证。

---

9. 维护

• 添加新模型时 → 在 generate_video.py::estimate_cost 和 transparent-proxy/apis/falai.py::_VIDEO_PRICING 中注册价格。
• 本技能有意不使用通过 fal 存储上传来托管素材：生产环境的 FAL_KEY 缺少 Serverless 权限。在权限变更前，请继续使用基于预览的方案。