ultimate-ai-media-generator-skill

Ultimate-AI-Media-Generator-Skill

概要

このスキルを使用すると、CyberBara API を確実に呼び出し、画像、動画、音声、音楽の生成タスクを作成して、クレジットを考慮したフローで最終的なメディア URL を返せます。

中国語の記事やリポジトリの宣伝用タイトル画像には、ユーザーが別の画像モデルを指定しない限り、デフォルトでモデル nano-banana-2-lite を使用します。まずテキストのないカバー背景を生成し、その後、公開するタイトルを正確かつ読みやすくするために、最終的な中国語の見出しをローカルで追加してください。

実装アーキテクチャ

ランタイムでは、階層化された Python アーキテクチャを使用します。

• scripts/cyberbara_api.py：薄いエントリーポイントのみ
• src/cyberbara_cli/cli.py：コマンドの解析とルーティング
• src/cyberbara_cli/usecases/：フローのオーケストレーション（生成＋ポーリング）
• src/cyberbara_cli/policies/：安全性とポリシーのルール（クレジットの見積もり＋正式な確認）
• src/cyberbara_cli/gateways/：CyberBara API の低レベルクライアント
• src/cyberbara_cli/config.py：API キーの検出とローカルへの保存
• src/cyberbara_cli/constants.py：固定のベース URL と共通定数

動作を拡張する場合、ビジネスルールは scripts/ ではなく、usecases/ または policies/ に記述してください。

ランタイム入力の設定

スクリプトでは、固定のベース URL を使用します。

https://cyberbara.com

API キーの検索順序：

1. --api-key
2. 環境変数 CYBERBARA_API_KEY
3. ローカルキャッシュファイル ~/.config/cyberbara/api_key
4. 対話型プロンプト（ターミナルで実行している場合）

推奨する初回セットアップコマンド：

python3 scripts/cyberbara_api.py setup-api-key "<api-key>"

または、環境変数から保存します。

export CYBERBARA_API_KEY="<api-key>"
python3 scripts/cyberbara_api.py setup-api-key --from-env

API キーが見つからない場合、スクリプトはただちに入力を求め、入手先を表示します。

https://cyberbara.com/settings/apikeys

--api-key または対話型プロンプトで API キーを入力すると、次の場所に保存されます。

~/.config/cyberbara/api_key

以降の実行ではこのキャッシュ済みのキーが再利用されるため、毎回入力する必要はありません。

標準的な生成フローの実行

1. 利用可能なモデルを確認します。
2. タスクのシーンでローカルメディア入力が必要な場合は、参照画像または動画をアップロードします。
3. 生成タスクを作成する前に、クレジットを見積もります。
4. 画像または動画の生成タスクを作成し、最終出力を待ちます。
5. 生成したメディアを自動的にローカルに保存して開きます。
6. 必要に応じて利用記録を確認します。

コマンド例：

# 1) List video models
python3 scripts/cyberbara_api.py models --media-type video

# Also available: image, audio, and music models
python3 scripts/cyberbara_api.py models --media-type audio
python3 scripts/cyberbara_api.py models --media-type music

# 2) Upload local reference images
python3 scripts/cyberbara_api.py upload-images ./frame.png ./style.jpg

# Upload local reference videos
python3 scripts/cyberbara_api.py upload-videos ./clip.mp4

# 3) Estimate credits
python3 scripts/cyberbara_api.py quote --json '{
  "model":"sora-2",
  "media_type":"video",
  "scene":"text-to-video",
  "options":{"duration":"10"}
}'

# 4) Create a video task (default behavior: wait for success, save outputs to ./media_outputs, auto-open)
python3 scripts/cyberbara_api.py generate-video --json '{
  "model":"sora-2",
  "prompt":"A calm drone shot over snowy mountains at sunrise",
  "scene":"text-to-video",
  "options":{"duration":"10","resolution":"standard"}
}'

# 5) Existing task: wait + save/open outputs
python3 scripts/cyberbara_api.py wait --task-id <TASK_ID> --interval 5 --timeout 900

画像と動画の生成では、デフォルトで確認が必要です。

# Single image request: script auto-quotes, then asks you to type CONFIRM
python3 scripts/cyberbara_api.py generate-image --json '{
  "model":"nano-banana-pro",
  "prompt":"A cinematic portrait under neon rain",
  "scene":"text-to-image",
  "options":{"resolution":"1k"}
}'

# Batch image requests (JSON array): script auto-quotes each request and prints total estimated credits
python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json

image-requests.json の形式：

[
  {
    "model": "nano-banana-pro",
    "prompt": "A cinematic portrait under neon rain",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  },
  {
    "model": "nano-banana-pro",
    "prompt": "A product still life with dramatic side light",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }
]

ユーザーの明示的な承認を得た後にのみ、--yes を使用してください。

python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json --yes
python3 scripts/cyberbara_api.py generate-video --json '{
  "model":"sora-2",
  "prompt":"A calm drone shot over snowy mountains at sunrise",
  "scene":"text-to-video",
  "options":{"duration":"10","resolution":"standard"}
}' --yes

python3 scripts/cyberbara_api.py generate-audio --json '{
  "model":"suno-sound-v5-5",
  "prompt":"A short cinematic whoosh with soft digital sparkle",
  "scene":"text-to-audio",
  "options":{"loop":false}
}' --yes

python3 scripts/cyberbara_api.py generate-music --json '{
  "model":"suno-music-v5",
  "prompt":"Warm lo-fi study music with mellow keys",
  "scene":"text-to-music",
  "options":{"instrumental":true}
}' --yes

自動保存とファイルを開く動作を制御します。

# keep waiting but do not auto-open media
python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json --yes --no-open

# custom output directory
python3 scripts/cyberbara_api.py generate-video --json '{...}' --yes --output-dir ./downloads

# submit only (no wait/save/open)
python3 scripts/cyberbara_api.py generate-video --json '{...}' --yes --async

スクリプトの機能を使用する

scripts/cyberbara_api.py では、次の機能を利用できます。

• setup-api-key：API キーをローカルキャッシュに保存します
• models：公開モデルを一覧表示します（--media-type image|video|audio|music は任意）
• upload-images：ローカルの画像ファイルを /api/v1/uploads/images にアップロードします
• upload-videos：ローカルの動画ファイルを /api/v1/uploads/videos にアップロードします
• quote：JSON リクエスト本文からクレジットコストを見積もります
• generate-image：クレジットを自動で見積もり、バッチリクエストの合計を計算し、正式な確認を求めてからタスクを作成し、完了を待って出力を保存・表示します
• generate-video：クレジットを自動で見積もり、バッチリクエストの合計を計算し、正式な確認を求めてからタスクを作成し、完了を待って出力を保存・表示します
• generate-audio：クレジットを自動で見積もり、バッチリクエストの合計を計算し、正式な確認を求めてからタスクを作成し、完了を待って出力を保存・表示します
• generate-music：クレジットを自動で見積もり、バッチリクエストの合計を計算し、正式な確認を求めてからタスクを作成し、完了を待って出力を保存・表示します
• task：タスク ID でタスクのスナップショットを取得します
• wait：タスクの状態が success、failed、または canceled になるまでポーリングし、その後、出力を保存・表示します
• balance と usage：クレジットを確認します
• raw：カスタムエンドポイントを直接呼び出します

長いペイロードには --json の代わりに --file request.json を使用してください。

API ペイロードのルールを適用する

• 認証情報は API キーで送信します（Authorization: Bearer <key> または x-api-key）。
• 公開リクエストフィールドは options.* の下にのみ送信します。
• 推論の曖昧さを避けるため、明示的な scene を指定してください。
• image-to-image と image-to-video には options.image_input を含めてください。
• video-to-video には options.video_input を含めてください。
• /api/v1/tasks/{taskId} を最終ステータスになるまでポーリングしてください。出力 URL が保証されるのは success の場合のみです。
• 画像、動画、音声、音楽の生成リクエストを送信する前に、必ず見積もりを取得し、ユーザーから明示的な確認を得てください。
• 画像、動画、音声、音楽を複数リクエストする場合は、送信前に合計の推定クレジット数を計算して提示してください。
• 出力ファイルはデフォルトで media_outputs/ に保存し、無効にされていない限り自動で開いてください。

詳細なモデルオプションを確認する

モデルの全一覧と例については、次のリファレンスファイルを使用してください。

• references/cyberbara-api-reference.mdx

大きなリファレンスをすばやく検索するには：

rg '^## |^### ' references/cyberbara-api-reference.mdx
rg 'kling-2.6|sora-2|veo-3.1|seedance' references/cyberbara-api-reference.mdx

よくあるエラーへの対処

• invalid_api_key または api_key_required：キーとヘッダーを確認してください。
• insufficient_credits：先に見積もりを取得するか、クレジットをチャージしてください。
• invalid_scene または scene_not_supported：モデルがサポートするシーンを選択してください。
• invalid_request：モデルごとの prompt と options の要件を確認してください。
• UPLOAD_INVALID：error.message と error.details の完全な内容を確認して報告してください。これらのプロバイダーによるアップロード検証エラーは、タスク ID が作成される前に発生します。
• task_not_found：タスク ID と環境のドメインを確認してください。