video

video

Starchild 上のすべての動画生成リクエストでこのスキルを使用してください。

基本原則: 提供されているスクリプトを呼び出してください。プロキシ／課金／アップロードの配管を再実装しないでください。

---

1. テキストから動画へ（最も一般的）

⚠️ 実行コンテキスト — まずこれを読んでください。 以下のコードブロックはPythonであり、シェルコマンドではありません。Starchild の bash ツールは /bin/bash -c を実行するため、exec(open(...)) を解析できません — これらをそのまま bash コマンドに貼り付けると、syntax error near unexpected token 'open' で失敗します。 また、python3 -c 内での exec(open(...)) は NameError: __file__ で失敗します。 これはスクリプトがパス解決に __file__ を使用しているためです。

bash ツール経由で呼び出す場合は、from exports import を伴う python3 - <<'EOF' を使用してください:

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

ヒアドキュメント（<<'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,
)

generate_video は、image_url が提供されるたびに、モデルパスを */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 を今後のすべての image-to-video / video-to-video タスクで再利用できます。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 なし。duration は文字列である必要があります ("5"、5 や "5s" ではない) — 下記の注意点を参照
premium-25	bytedance/seedance-2.5/text-to-video	トークンベース	text-to-video、image-to-video、reference-to-video をサポートします。resolution (480p/720p)、aspect_ratio (6つのサポートされる比率)、および 4〜30 秒の整数の duration が必要です。estimate_cost(..., aspect_ratio=...) で見積もります。
—	xai/grok-imagine-video/v1.5/image-to-video	$0.41 (480p) / $0.71 (720p) / 5秒あたり	image-to-video 専用 (単一の必須 image_url、image_urls は不可); 見積もりには +$0.01 の入力画像サーチャージが含まれます。⚠️ resolution="1080p" は上流のスキーマ上は有効ですが、公開価格がありません — プロキシは fail-closed で 400 を返して拒否します
—	fal-ai/kling-video/v3/turbo/standard/text-to-video	$0.56 / 5秒あたり	Kling v3 Turbo Standard、一律 $0.112/秒; .../turbo/pro/... = $0.14/秒 ($0.70/5秒); .../v3/4k/... = $0.42/秒 ($2.10/5秒)。すべてに i2v バリアントがあります
—	alibaba/happy-horse/v1.1/text-to-video	$0.70 (720p) / $0.90 (1080p) / 5秒あたり	v1.1 には独自の 1080p ティア $0.18/秒 があります (v1.0 の 2 倍ルールではありません); /image-to-video、/reference-to-video もあります
—	fal-ai/minimax_h3/text-to-video	プロキシの価格設定が適用されます	text-to-video、image-to-video、reference-to-video をサポートします。reference-to-video では image_urls=[...] を渡します; ペイロードは上流の reference_image_urls に変換されます。

⚠️ Happy Horse のデフォルト解像度は上流では 1080p です (v1.0 と v1.1): resolution を省略すると 1080p ティアで請求されます (v1.1 5秒 = $0.90; v1.0 ref2v 5秒 = $1.40)。安い料金にするには resolution="720p" を明示的に渡してください。無効な解像度の値はプロキシによって 400 で拒否されます。

Reference-to-video: 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 値は安全に価格設定できないため、プロキシは拒否します。

generate_video(model=...) に完全なモデル ID を渡すことでオーバーライドできます。image-to-video バリアントは 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（プレビュー配信）	どのプレビューを停止するかユーザーに確認してください。自動で kill しないでください
COMPLETED 後の downstream_service_error	レンダリング途中で参照アセットのホストが失敗しています — 16:9 に再エンコード／リサイズし、再公開してリトライしてください
HTTP 402 insufficient_credits	残高をチャージしてください。コストは送信時に事前課金されます
HTTP 403 endpoint_not_allowed	sc-proxy は承認済みの fal 動画エンドポイントのみ許可します。モデル表から 1 つ選んでください
上流で生成が FAILED	プロンプトを短くし、特殊なトークンを削除し、モデルを変更する前に一度リトライしてください
duration で HTTP 422 literal_error（Seedance Mini）	Mini では duration を 文字列（"5"、"10"、"auto"）で指定する必要があり、int でも "5s" でもありません。model に seedance-2.0/mini が含まれる場合、generate_video() がこれを自動的にエンコードします — リクエストボディを手動で組み立てた場合にのみ発生します。他の Seedance のバリアントは従来どおり int／"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 を手動で送信しないでください。
ジョブが 15 分以上 IN_PROGRESS のまま	request_id を保存し、後で poll_status.py で再開してください
ユーザーが fal.media のリンクについて「何も表示されない」／「空白ページ」と報告する	想定どおりです — fal は CSP: sandbox; default-src 'none' で配信します。生の URL ではなく、result["local_path"] にあるローカルファイルを渡してください（§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 権限がないためです。状況が変わるまでは、プレビューベースのアプローチを使い続けてください。