genviral

genviral Partner API スキル

概要： @genviral/cli npm パッケージを使用して、60 以上の Partner API コマンドを実行します。正規の REST リファレンスは docs.genviral.io です（まず llms.txt と、POST /posts のペイロード形式を確認できる Create Post を参照してください）。基本的な流れは、get-pack → 画像を分析（メタデータ＋ビジョン）→ pinned_images を指定して generate → render → 目視でレビュー（必須のゲート）→ create-post → workspace/performance/log.json に記録、です。TikTok のコピー作成フロー：copy-tiktok-preview → copy-tiktok-import（pack_id または pack_images のいずれか一方のみを指定）。Studio AI：studio-models → studio-generate-image（同期）または studio-generate-video → studio-video-status --poll（非同期）。フォルダー：create-folder → folder-items-add でファイルやスライドショーを整理します。分析データの照合：analyticsId／id、platformPostId、genviralPostId は別々の識別子として扱います。分析行を作成済みの投稿に対応付けるには、genviralPostId または externalId を使用します。認証には GENVIRAL_API_KEY を使用します。設定は defaults.yaml にあります。インスタンスデータは workspace/ にあります。

このスキルでできること

• 複数プラットフォームへの投稿： TikTok、Instagram、YouTube、Pinterest、LinkedIn、Facebook、X、Bluesky に動画、スライドショー、またはテキストのみの投稿を作成します（GET /accounts から各アカウントの capabilities を確認してください）
• Studio AI による生成： API 経由で AI モデルを使用して画像（同期）や動画（非同期）を生成します
• ファイル管理： 動画や画像を genviral の CDN にアップロードし、フォルダーで整理します
• フォルダー管理： アップロード、AI 画像、AI 動画、スライドショー用のネストされたフォルダーを作成します
• AI スライドショーの生成： プロンプトから写真のカルーセルを作成し、画像にレンダリングします
• テンプレートシステム： 再利用できるスライドショーの構成を作成し、成果の良かった投稿をテンプレートに変換します
• パック管理： 画像パックをスライドショーの背景として使用します
• 分析： KPI、投稿ごとの指標、追跡対象アカウント、更新トリガーを管理します
• ニッチ分野のインテリジェンス： 1 回の呼び出しで、ハッシュタグ、サウンド、クリエイター、投稿時間帯、フックの切り口を調査します（trend-brief）
• コンテンツパイプライン： プロンプトから投稿までを完全に自動化します
• パフォーマンスの追跡： 投稿ログ、フックの追跡、週次レビューを行います
• フックライブラリ： 実績のあるコンテンツフックのライブラリを維持し、発展させます

動作の仕組み

1. メディアを生成またはアップロードします
2. 1 つ以上のアカウントを対象に投稿を作成します
3. スケジュール設定または公開します（TikTok のスライドショーでは、公開前にトレンドの音声を追加できるよう、下書きとして保存することもできます。最適な結果を得るには、音楽の選択に人の判断が必要です）
4. 分析を通じてパフォーマンスを追跡します
5. 学習して最適化します

分析データの識別に関する重要なルール：

• analyticsId は分析行の ID です（id は同じ値を示すレガシーエイリアスです）
• platformPostId はプラットフォーム固有の投稿／動画 ID です
• genviralPostId は、照合に成功した場合の元の Genviral 投稿 ID です
• externalId は、存在する場合、元の Partner API external_id です
• BYO TikTok MEDIA_UPLOAD では、下書き／受信トレイの publish_id は公開後の TikTok 動画 ID ではありません。ユーザーが TikTok で実際に公開した後、最近の未照合の下書きをベストエフォートで照合します。そのため、古い行では genviralPostId／externalId が null のままの場合があります。

すべての設定は defaults.yaml にあります。シークレットは環境変数で管理します。投稿した内容はすべて Genviral ダッシュボードに表示されます。

初回セットアップ

新規インストールの場合は、docs/setup.md を読み、会話形式でユーザーのオンボーディングを進めてください。

1. API キーを設定し、動作を確認します
2. アカウントを一覧表示し、投稿先を選びます
3. 画像の方針を相談します（既存のパック、新規作成、投稿ごとに生成、または組み合わせ）
4. 必要に応じて、製品のコンテキストとブランドのトーンを一緒に設定します

ハードコードされたデフォルト値はありません。ユーザーの希望を尋ね、それに合わせて調整してください。このスキルを通じて行ったことはすべて Genviral ダッシュボードに表示されるため、ユーザーは常に全体を確認し、管理できます。

ファイル構成

genviral/
  SKILL.md                  # This file (kernel + routing)
  README.md                 # Human-facing overview
  defaults.yaml             # API config and defaults

  docs/
    setup.md                # Onboarding guide (conversational, 5 phases)
    api/
      accounts-files.md     # accounts, upload, list-files
      folders.md            # folder CRUD, move, ancestors, items management
      posts.md              # create-post, update-post, retry, list, get, delete
      slideshows.md         # generate/render/update + TikTok copy preview/import + text styles
      packs.md              # pack CRUD + smart image selection (MANDATORY reading for any pack workflow)
      templates.md          # template CRUD + create-from-slideshow
      analytics.md          # all analytics commands
      studio.md             # Studio AI: generate images/videos, list models, poll status
      subscription.md       # subscription status, credits, tier
      pipeline.md           # content pipeline, performance loop, CTA testing, platform tips
      errors.md             # error codes and troubleshooting
    references/
      analytics-loop.md     # Full analytics feedback loop and weekly review process
      competitor-research.md # How to research competitors
    prompts/
      slideshow.md          # Prompt templates for slideshow generation
      hooks.md              # Prompt templates for hook brainstorming

  workspace/                # All instance/customer data (override with GENVIRAL_WORKSPACE_DIR)
    content/
      scratchpad.md         # Working content plan and drafts
      calendar.json         # Upcoming planned posts
    context/
      product.md            # Product description, value props, target audience
      brand-voice.md        # Tone, style, do's and don'ts
      niche-research.md     # Platform research for the niche
    hooks/
      library.json          # Hook instances (grows over time, tracks performance)
      formulas.md           # Hook formula patterns and psychology
    performance/
      log.json              # CANONICAL post record (single source of truth)
      hook-tracker.json     # Hook and CTA tracking with metrics (the feedback loop)
      insights.md           # Agent learnings from performance data
      weekly-review.md      # Weekly review notes
      competitor-insights.md # Competitor research findings

  scripts/
    genviral.sh               # Optional wrapper that delegates to the npm CLI and sets GENVIRAL_CONFIG
    update-skill.sh           # Self-updater

コマンドの振り分け

現在のタスクに必要なものだけを読み込みます。

タスク	読むもの
生の POST /posts JSON、プロバイダー設定、冪等性、スケジュール設定のルール	docs.genviral.io/llms.txt + 投稿の作成（スキルのドキュメントに仕様全体を重複して記載しないでください）
アカウントの検索、ファイルのアップロード	docs/api/accounts-files.md
フォルダー管理（作成、一覧表示、移動、削除、アイテム）	docs/api/folders.md
インフルエンサー／一貫性のあるキャラクター	docs/api/influencers.md
投稿の作成、更新、一覧表示、削除	docs/api/posts.md
スライドショーの生成、TikTok コピーのインポート、レンダリング、編集、テキストスタイル	docs/api/slideshows.md
パック管理、画像の選択（あらゆるパックのワークフロー）	docs/api/packs.md
テンプレートの作成と管理	docs/api/templates.md
分析クエリとターゲット管理	docs/api/analytics.md
Studio AI：画像や動画の生成、モデルの一覧表示	docs/api/studio.md
サブスクリプション：クレジット、プラン、更新日の確認	docs/api/subscription.md
特定のニッチをすばやく調査（トレンド＋競合＋フック）	docs/api/analytics.md、docs/references/competitor-research.md、docs/prompts/hooks.md
コンテンツ制作の全工程、パフォーマンスの改善サイクル、CTA のテスト	docs/api/pipeline.md
エラーコード、トラブルシューティング	docs/api/errors.md

ニッチ調査モード（ユーザーからニッチの調査を依頼された場合）

「このニッチを調査して」「このニッチで効果があるものを見つけて」「ニッチの情報を教えて」などの依頼があった場合：

1. まずニッチのキーワードで trend-brief を実行します（基準として 7d を使い、必要に応じて最新情報を得るため 24h も実行します）。
2. 次の情報を抽出して報告します：人気のハッシュタグ、人気のサウンド、人気のクリエイター、投稿に適した時間帯（UTC）、推奨するフックの切り口。
3. docs/references/competitor-research.md を使って競合を詳しく調査します（最低 3～5 アカウント）。
4. 次の内容を含む、簡潔で実行に移せる結果を作成します。
   • テストするフックの切り口を 3 つ
   • CTA の提案を 2 つ
   • 最適な投稿時間帯を 2 つ
   • まず試すハッシュタグを 5 つ
   • 活用できる「ギャップ」の洞察を 1 つ
5. 調査結果を workspace/performance/competitor-insights.md に保存し、以降のコンテンツ用プロンプトに活用します。

TikTok コピーのリミックスモード（ユーザーから「似たものを新しく作って」と依頼された場合）

ユーザーが TikTok のスライドショーのアイデアをもとに、新しいビジュアルを生成したい場合：

1. まず copy-tiktok-preview を実行し、preview_id、ソース画像の URL、スライド数を記録します。
2. copy-tiktok-import を実行します。パックのソース（pack_id または pack_images）は必ず 1 つだけ指定し、テキストオーバーレイを抽出して編集可能なスライドに割り当てます。
3. 各ソーススライドの画像を参照入力として使用し、Studio で google/nano-banana-2 を使って差し替え用の画像を生成します。
   • コマンド：studio-generate-image --model-id "google/nano-banana-2" --image-urls "<source_url>" --prompt "<product-aware transformation prompt>"
4. workspace/context/product.md の製品コンテキストを使ってプロンプトを作成し、生成されるビジュアルが宣伝対象の製品に関連したものになるようにします。
5. インポートしたテキスト要素は維持または編集しつつ、生成した URL でスライドの背景を置き換えます（update --slides-file ...）。
6. 投稿前にレンダリング（render）してレビュー（review）します。ビジュアルの品質確認は必ず行ってください。

分析データと投稿の照合モード（ユーザーから「分析データを投稿に照合して」と依頼された場合）

1. analytics-posts --json を取得します。
2. 分析データの行を Genviral の投稿に照合するには、genviralPostId を優先して使います。
3. 呼び出し元が独自に使用している安定した ID が必要な場合は、externalId を使います。
4. analyticsId／従来の id は、分析データの行を識別するためだけに使います。
5. platformPostId は、TikTok／Instagram／YouTube のプラットフォーム固有の投稿 ID としてのみ扱います。
6. BYO TikTok の下書き（MEDIA_UPLOAD）では、下書きのアップロードがすぐに照合可能になるとは限りません。下書きの publish_id は、人が TikTok から投稿し、Genviral が最終的な公開 TikTok 動画 ID に解決した後にのみ照合可能になります。

正式な API リファレンス

日常的な自動化には CLI を使用してください。REST ペイロード、検証ルール、プロバイダー固有のフィールドについては、CLI とあわせて docs.genviral.io を信頼できる情報源として扱ってください。

1. llms.txt — エージェント向けのドキュメント全体のインデックスです（エンドポイント一覧をプロンプトにコピーするよりもこちらを優先してください）。
2. 投稿の作成 — POST /api/partner/v1/posts の本文：caption、accounts、media、scheduled_at、external_id、music_url、およびプロバイダー設定。

スキルファイルに Partner API の仕様全体を貼り付けたり、維持したりしないでください。ここではワークフローを要約し、リクエストの作成やデバッグ時には上記のドキュメントから構造を取得してください。

投稿ペイロードに関する注意（表と制限については「投稿の作成」を参照）：

• 最初に GET /accounts を呼び出し、各アカウントの capabilities（supported_content_kinds、caption_limit）を使用してください。capabilities.settings_schema はダッシュボードの投稿作成画面を反映しており、Partner API のフィールド名とは一致しない場合があります。
• TikTok と Pinterest の設定は、作成時にトップレベルの tiktok と pinterest に指定します。settings.tiktok や settings.pinterest ではありません。
• それ以外のプラットフォームでは、settings.<provider> を使用します（例：settings.youtube、settings.x、settings.instagram または settings.instagram-standalone、settings.bluesky）。
• 選択したすべてのアカウントが text_only に対応している場合に限り、media を省略してください。
• music_url は TikTok 専用です（TikTok 以外のアカウントが1つでも選択されていると拒否されます）。
• scheduled_at はタイムゾーンオフセットを含む ISO 8601 形式で指定する必要があります。実際にスケジュールする場合は、少なくとも2分後の日時を指定してください。
• 冪等性には external_id を優先してください（最大128文字）。同じキーと同じペイロードを再送すると、duplicate: true が返されます。

絶対に守るルール

読み込んだドキュメントの内容にかかわらず、以下を適用してください。

1. パックを使ってスライドショーを生成するときは、必ず pinned_images を使用してください。 --pack-id だけを指定して generate を呼び出してはいけません。サーバーがランダムな画像を選択します。パックを使うワークフローを実行する前に、docs/api/packs.md を読んでください。

2. 投稿前に、レンダリングされたすべてのスライドを必ず目視で確認してください。 読みやすさに問題のあるスライドがあれば修正してください。これは必須のゲートであり、提案ではありません。

3. 投稿後は直ちに、必ず workspace/performance/log.json に記録してください。 これが正式な記録です。

4. 投稿後は必ずフックトラッカーにエントリーを追加してください。 トラッキングがなければ学習もありません。

5. 生成するコンテンツで em ダッシュを使用してはいけません。

6. workspace/ を尊重してください。 インスタンスデータはすべてここに保存します。状態ファイルをスキルのルートに書き込まないでください。

CLI のインストール

Partner API CLI を一度だけグローバルにインストールします。

npm install -g @genviral/cli

npm パッケージでは genviral と genviral-cli が公開されています。手順や自動化では genviral バイナリを優先してください。

モノレポからローカルにインストールする場合（npm 公開前）：

pnpm --filter @genviral/partner-api-contracts pack --pack-destination /tmp
pnpm --filter @genviral/cli pack --pack-destination /tmp
npm install -g /tmp/genviral-partner-api-contracts-0.1.0.tgz /tmp/genviral-cli-0.1.0.tgz

スキルの scripts/genviral.sh は利便性のためのラッパーにすぎません。npm の genviral バイナリに処理を転送し、環境変数がすでに設定されていない場合は、このスキルの defaults.yaml を GENVIRAL_CONFIG に設定します。Partner API コマンド用の独立したシェル実装として説明したり、依存したりしないでください。

CLI の使用方法

genviral <command> [options]
# or from the skill directory:
./scripts/genviral.sh <command> [options]

環境変数 GENVIRAL_API_KEY が必要です（形式：public_id.secret）。CLI は --config または GENVIRAL_CONFIG からデフォルト設定を読み込みます。スキルのラッパーは、ローカルでスキルを実行する際に GENVIRAL_CONFIG を defaults.yaml に設定します。ワークスペースのパスを変更するには GENVIRAL_WORKSPACE_DIR を設定してください（デフォルトはスキルディレクトリからの相対パス workspace/ です）。

自動更新

このスキルには、fdarkaou/genviral-skill の最新バージョンに合わせて、スキルが管理するファイルを同期する自動更新機能が含まれています。

bash scripts/update-skill.sh           # check + apply if updates available
bash scripts/update-skill.sh --dry-run # preview only, no changes
bash scripts/update-skill.sh --force   # force re-apply even if already current

更新対象（スキル管理）： README.md、SKILL.md、scripts/、docs/（すべてのサブディレクトリ）

変更されないもの（ユーザー管理）： workspace/ — データ、コンテキスト、フック、パフォーマンスログは常に保持されます。

---

注意事項

• Partner API のベース URL：https://www.genviral.io/api/partner/v1（はじめにを参照）
• 投稿先：TikTok、Instagram、YouTube、Facebook、Pinterest、LinkedIn、X、Bluesky（アナリティクスの対象はTikTok、Instagram、YouTubeのみ）
• 動画、スライドショー、テキストのみの投稿に対応しています（アカウントごとのcapabilitiesに準拠）
• ホスト型アカウントとBYOアカウントで利用できます。TikTok固有の設定を使用する場合、作成時にBYO TikTokが必要です
• 投稿は予約投稿するか、キューに追加してすぐに公開できます
• TikTokのスライドショーの下書き：最上位のtiktok.post_mode: MEDIA_UPLOADを使用すると、音声を追加するための下書き受信箱に保存されます
• BYO TikTokの下書きアップロード（MEDIA_UPLOAD）では、Genviralの投稿がすぐに作成されますが、最終的な公開TikTok動画IDは、ユーザーがTikTokで公開した後にのみ作成されます。analytics-postsでは、関連付けにgenviralPostIdまたはexternalIdを使用してください。analyticsId／従来のidはアナリティクス行のID、platformPostIdはTikTokネイティブのIDとして扱ってください。

Meta Ads コンパニオン（同梱）

このリポジトリには、GenviralのStudio APIを使って広告クリエイティブを生成する、自律型Meta（Facebook／Instagram）広告マネージャー兼8段階のAIキャンペーンビルダーであるmeta-adsコンパニオンガイドがmeta-ads/ディレクトリに含まれています。

同梱のワークフローとセットアップガイドについては、meta-ads/INSTRUCTIONS.mdを参照してください。

単体でも利用できます：fdarkaou/meta-ads-skill