sora

Sora 動画生成スキル

現在のプロジェクト用の短い動画クリップを作成または管理します（製品デモ、マーケティング用スポット、シネマティックなショット、UI モックアップなど）。デフォルトは sora-2 と構造化されたプロンプト拡張ワークフローで、再現性のある実行のために同梱の CLI を優先します。注意：$sora はプロンプト内のスキルタグであり、シェルコマンドではありません。

使用するタイミング

• プロンプトから新しい動画クリップを生成する
• 既存の動画を ID で リミックスする
• ステータスの確認、ジョブ一覧の取得、アセット（動画／サムネイル／スプライトシート）のダウンロードを行う
• バッチ実行（多数のプロンプトやバリエーション）

判断フロー（作成 vs リミックス vs ステータス／ダウンロード vs バッチ）

• ユーザーが 動画 ID を持っていて変更を望む → リミックス
• ユーザーが 動画 ID を持っていてステータスやアセットを望む → ステータス／ポーリング／ダウンロード
• ユーザーが多数のプロンプトやアセットを必要とする → create-batch
• ユーザーが同じショットで被写体や詳細だけを変えた 2 つのバージョンを求める → まず基準となる 作成 を行い、その後バリエーションとして リミックス を行う
• それ以外 → 作成（すぐに使えるアセットが一度に必要な場合は create-and-poll）

ワークフロー

1. 目的を決める：作成、リミックス、ステータス／ダウンロード、バッチのいずれか。
2. 入力を収集する：プロンプト、モデル、サイズ、秒数、および入力参照画像（ある場合）。
3. バッチの場合：tmp/ 配下に一時的な JSONL を作成し（1 行に 1 ジョブ）、一度実行してから JSONL を削除する。
4. 構造化プロンプトを事前に書くのではなく、CLI の拡張フラグ（--use-case、--scene、--camera など）を優先して使う。すでに構造化プロンプトファイルを作成している場合は、二重にラップされないよう --no-augment を渡す。
5. 同梱の CLI（scripts/sora.py）を適切なデフォルト値で実行する（references/cli.md を参照）。長いプロンプトの場合は、シェルエスケープの問題を避けるため --prompt-file を優先する。プロンプトがすでに構造化されている場合は --no-augment と組み合わせる。
6. 非同期ジョブは、完了するまでポーリングする（または create-and-poll を使う）。
7. アセット（動画／サムネイル／スプライトシート）をダウンロードし、ローカルに保存する。
8. 呼び出し中に作成された中間ファイル（例：prompt.txt、remix_job.json、一時的な JSONL）を削除する。サンドボックスが rm をブロックする場合は、クリーンアップを省略するか、エラーを表示せずにファイルを空にする。
9. プロンプトごとに 1 つの対象を絞った変更を加えて反復する。

認証

• ライブ API 呼び出しには OPENAI_API_KEY の設定が必要です。

キーが設定されていない場合は、ユーザーに次の手順を案内してください：

1. OpenAI プラットフォームの UI で API キーを作成する：https://platform.openai.com/api-keys
2. システムの環境変数として OPENAI_API_KEY を設定する。
3. 必要に応じて、ユーザーの OS／シェルに合わせた環境変数の設定を案内することを申し出る。

• キー全体をチャットに貼り付けるよう求めないでください。ローカルで設定してもらい、準備ができたら確認してもらいます。

デフォルトとルール

• デフォルトモデル：sora-2（より高い忠実度が必要な場合は sora-2-pro を使用）。
• デフォルトサイズ：1280x720。
• デフォルト秒数：4（指定可能な値："4"、"8"、"12"（文字列））。
• サイズと秒数は必ず API パラメータで設定する。プロンプトの記述では変更されない。
• OpenAI Python SDK（openai パッケージ）を使用し、生の HTTP は使用しない。
• ライブ API 呼び出しの前に必ず OPENAI_API_KEY を要求する。
• uv キャッシュの権限エラーが発生した場合は、UV_CACHE_DIR=/tmp/uv-cache を設定する。
• 入力参照画像は jpg／png／webp である必要があり、ターゲットサイズに合わせるべきです。
• ダウンロード URL は約 1 時間で期限切れになるため、アセットは自身のストレージにコピーしてください。
• 同梱の CLI を優先し、ユーザーに依頼されない限り scripts/sora.py を 決して変更しない。
• Sora は音声を生成できます。ユーザーがナレーションや音声を求める場合は、Audio: と Dialogue: の行で明示的に指定し、短く保ってください。

API の制限事項

• モデルは sora-2 と sora-2-pro に限定されます。
• Sora モデルへの API アクセスには、組織認証済みのアカウントが必要です。
• 長さは 4/8/12 秒に限定され、seconds パラメーターで設定する必要があります。
• API は seconds を文字列の列挙型（"4"、"8"、"12"）として扱います。
• 出力サイズはモデルごとに制限されています（対応サイズは references/video-api.md を参照してください）。
• 動画の作成は非同期で行われるため、ダウンロードの前に完了をポーリングで確認する必要があります。
• レート制限は利用ティアごとに適用されます（具体的な上限は記載しません）。
• コンテンツの制限は API によって適用されます（後述のガードレールを参照してください）。

ガードレール（必ず適用すること）

• 18 歳未満の視聴者に適したコンテンツのみを対象とします。
• 著作権で保護されたキャラクターや著作権で保護された音楽は使用しないでください。
• 実在の人物（公人を含む）は対象にしないでください。
• 人の顔が写っている入力画像は拒否されます。

プロンプトの拡張

プロンプトを、構造化された本番運用向けの仕様に書き直します。暗黙的な詳細のみを明示化し、新しいクリエイティブな要件を発明しないでください。

テンプレート（関連する行のみを含めること）:

Use case: <where the clip will be used>
Primary request: <user's main prompt>
Scene/background: <location, time of day, atmosphere>
Subject: <main subject>
Action: <single clear action>
Camera: <shot type, angle, motion>
Lighting/mood: <lighting + mood>
Color palette: <3-5 color anchors>
Style/format: <film/animation/format cues>
Timing/beats: <counts or beats>
Audio: <ambient cue / music / voiceover if requested>
Text (verbatim): "<exact text>"
Dialogue:
<dialogue>
- Speaker: "Short line."
</dialogue>
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

拡張のルール:

• 簡潔に保ち、ユーザーがすでに示唆または別途提供した詳細のみを追加します。
• リミックスの場合は、不変要素を明示的に列挙します（「同じショット、変更するのは X のみ」）。
• 成功を妨げる重要な詳細が不足している場合は質問し、そうでなければ処理を進めます。
• 構造化されたプロンプトファイルをコマンドラインツールに渡す場合は、ツールが再度ラップしないように --no-augment を追加します。

例

生成の例（単一ショット）

Use case: product teaser
Primary request: a close-up of a matte black camera on a pedestal
Action: slow 30-degree orbit over 4 seconds
Camera: 85mm, shallow depth of field, gentle handheld drift
Lighting/mood: soft key light, subtle rim, premium studio feel
Constraints: no logos, no text

リミックスの例（不変要素）

Primary request: same shot and framing, switch palette to teal/sand/rust with warmer backlight
Constraints: keep the subject and camera move unchanged

プロンプト作成のベストプラクティス（短いリスト）

• 1 ショットにつき、主要なアクションを 1 つと、カメラの動きを 1 つにします。
• タイミングには、回数やビート（「2 歩、間、振り向く」）を使います。
• UI や画面上のテキストの場合は、テキストを短くし、カメラを固定したままにします。
• アーティファクト（ちらつき、ジッター、高速な動き）が出る場合は、簡単な回避指示を追加します。
• 短いプロンプトはより創造的になり、長いプロンプトはより制御しやすくなります。
• セリフは専用のブロックに入れ、4〜8 秒のクリップ向けに行を短く保ちます。
• リミックスでは、不変要素（同じショット、同じカメラの動き）を明示します。
• 連続性を保つため、一度に 1 か所だけ変更する形で反復的に修正します。

アセット種別ごとのガイダンス

リクエストが特定の成果物を対象とする場合は、これらのモジュールを使用します。対象に特化したテンプレートとデフォルト設定を提供します。

• シネマティックショット: references/cinematic-shots.md
• ソーシャル広告: references/social-ads.md

コマンドライン + 環境に関する注意

• コマンドラインのコマンドと例: references/cli.md
• API パラメーターのクイックリファレンス: references/video-api.md
• プロンプト作成のガイダンス: references/prompting.md
• サンプルプロンプト: references/sample-prompts.md
• トラブルシューティング: references/troubleshooting.md
• ネットワーク/サンドボックスのヒント: references/codex-network.md

リファレンスマップ

• references/cli.md: scripts/sora.py を使って、作成/ポーリング/リミックス/ダウンロード/バッチ処理を実行する方法。
• references/video-api.md: API レベルの設定項目（モデル、サイズ、長さ、バリアント、ステータス）。
• references/prompting.md: プロンプトの構造と反復的な改善のガイダンス。
• references/sample-prompts.md: コピー＆ペーストできるプロンプトのレシピ（例のみ。追加の理論は含みません）。
• references/cinematic-shots.md: 映画風ショットのテンプレート。
• references/social-ads.md: 短いソーシャル広告のビート向けテンプレート。
• references/troubleshooting.md: よくあるエラーと対処法。
• references/codex-network.md: ネットワークと承認に関するトラブルシューティング。