競合がYouTubeに公開している動画広告を要約し、訴求・構成・尺・出演者の使い方を比較表にまとめて、広告主への月次の報告に使う

処理の起点を決める

毎週月曜の朝に、Python のプログラムを定時で動かします。 月次の報告の前にまとめて拾うと、（c）の見落としが月末に一度に見つかり、要約と確認が報告の週に詰まります。週ごとに拾えば、担当者の確認も週に数本ずつで済みます。

AIの要約は、担当者が「要約する」を付けた時点で動かします。 候補の一覧の列に印が付いたものを、プログラムが30分ごとに拾います。拾い上げと要約を分けるのは、広告でない動画にAIの費用と担当者の確認の時間を使わないためです。

月次の報告の下書きは、担当者が比較表の確認を終えて「報告の下書き」を押したときに作ります。 確かめる前の値で下書きを作ると、誤った値が報告の文章に入ります。

入力データを集める

質を決めるのは、比べる軸の選択肢です。 訴求なら「価格・値引き」「品質・成分」「実績・受賞」「利用者の声」「限定・期間」「手軽さ」のように、広告主の業種ごとに6〜8個を決めます。 選択肢が多すぎると、AIの選び方がばらつき、少なすぎると「その他」ばかりになります。

広告主の動画も、同じ軸で要約しておきます。 比較表の左端に広告主の動画を置くと、「競合は今月3社とも利用者の声で始まり、自社だけが価格で始まっている」のような違いが一目で分かります。

データの取得方法を決める

前回の実行より後に公開された動画だけを、候補に足します。 snippet.publishedAt は公開された日時で、後から公開に切り替えた動画では、アップロードの日時と違うとされています。前回の実行の日時と比べ、それより後のものを拾います。

status.privacyStatus が public の動画だけを要約の対象にします。 Gemini API に渡せるのは公開の動画だけなので、unlisted（限定公開）の動画は、候補の一覧に「対象外」として残すだけにします。

尺の ISO 8601 の値は、Python で秒に直します。 PT30S なら30秒、PT1M15S なら75秒です。比較表では秒で並べ、15秒以下・30秒前後・60秒以上のように区切って傾向を見ます。

AIへ渡す前に整形する

1. 新しい動画の絞り込み … 前回の実行より後に公開され、公開の状態が public のものだけを候補にします
2. 重複の除外 … 同じ動画が別の再生リストから拾われても、動画のIDで1つにします
3. 担当者の選別 … 候補の一覧で「要約する」が付いたものだけを次に進めます
4. 長い動画の扱い … 尺が10分を超える動画は、要約の前に担当者に確かめます。広告ではないことが多いためです
5. 軸の準備 … その広告主の業種の軸の選択肢を、軸のシートから取り出しておきます
6. 広告主の動画の要約 … 広告主の新しい動画も、同じ流れと同じ軸で要約し、比較表の左端に置きます。一度確かめた値は、翌月以降は取り直さず使い回します

動画のファイルは、こちらで保存しません。 YouTube のデベロッパーポリシーは、事前の書面の承認なしに、YouTube の映像・音声のコンテンツをダウンロードしたり、コピーを保存したりしないことを求めています。この構成では URL を Gemini API に渡すだけにし、動画を手元に落として静止画や音声に分ける処理は作りません。

4番の10分の区切りは、費用と確認の時間のためでもあります。 公式の説明では、既定の解像度で動画1秒あたりおよそ100トークンかかるとされています。長い商品紹介を誤って要約に回すと、1本で短い広告の何十本分の費用になります。

AIに処理させる

動画1本ごとに、次の項目を返させます。

出演者は「立場」で答えさせ、誰かを当てさせません。 顔から人物の名前を推測させると、誤った名前が比較表と報告に残ります。 名前を書くのは、画面のテロップや題名・概要に名前が出ているときだけにし、その場合も根拠の時刻を付けさせます。

3行目がいちばん起きやすい失敗です。 AIは要約の最後に「訴求が明確で効果的な広告です」と書きがちで、それが報告に入ると、根拠の無い評価を広告主に伝えることになります。

指示内容を固定する

あなたは広告代理店のプランニングチームで、競合の動画広告の中身を記録する立場です。
渡した動画を見て聞いて、決めた項目を答えてください。

【この広告主の業種】{industry}
【訴求の選択肢】{appeal_options}
【展開の型の選択肢】{structure_options}
【CTAの選択肢】{cta_options}
【出演者の立場の選択肢】{cast_options}

【答えること】
- 訴求：主を1つ、副を2つまで。それぞれ根拠の場面の時刻（MM:SS）
- 冒頭：最初の5秒に映るものと言われること。商品が初めて映る時刻
- 展開：場面ごとの型と開始の時刻
- 締め：CTAの種類と表示の時刻
- 出演者：立場と話し方
- 画面の文字：価格・期間・注釈など主なものと時刻

【厳守事項】
- 選択肢に当てはまらないときは other を選び、短く説明してください。無理に近いものを選ばないでください。
- すべての答えに、根拠の場面の時刻を付けてください。時刻を付けられない答えは書かないでください。
- 動画の長さ（秒数）を書かないでください。
- 出演者の名前を顔から推測しないでください。画面の文字に名前が出たときだけ、その時刻とあわせて書いてください。
- 広告の出来や効果を評価しないでください。
- 表現が法令に触れるかどうかを書かないでください。

「時刻を付けられない答えは書かない」が、この構成の確認を軽くします。 時刻が付いていれば、担当者はその場面だけを見て確かめられます。時刻の無い答えは、確かめるのに動画を頭から見ることになり、AIを使った意味が薄れます。

「無理に近いものを選ばない」は、軸を育てるための行です。 other の説明が毎月同じ内容で出てくるなら、それは選択肢に足すべき訴求です。other が多い軸は、軸のシートを見直す合図になります。

出力形式を固定する

構造化出力で、動画1本ごとに次の形のJSONを受け取ります。

{
  "video_id": "",
  "appeal": { "main": "price | quality | track_record | testimonial | limited | ease | other",
              "main_time": "00:03", "sub": [ { "value": "", "time": "" } ],
              "other_note": "" },
  "opening": { "first_5s": "", "product_first_seen": "00:02 | not_shown" },
  "structure": [ { "type": "problem | demo | comparison | testimonial | offer | other",
                   "start": "00:00" } ],
  "cta": { "type": "purchase | inquiry | visit | search | app | none", "time": "" },
  "cast": { "role": "celebrity_like | user_role | employee | expert_role | animation | none | uncertain",
            "speech": "address | dialogue | narration_only", "name_from_caption": "", "time": "" },
  "on_screen_text": [ { "text": "", "time": "" } ]
}

選択肢を enum にして、軸の値をそろえます。 Gemini API の構造化出力は、/v1beta/interactions の response_format に mime_type: "application/json" とスキーマを入れて指定します。公式のページは、スキーマに合ったJSONでも値が正しいとは限らないので、アプリケーションの側で確かめるよう案内しています。Python では、時刻が MM:SS の形で、動画の尺（videos.list の値）を超えていないかを確かめます。尺を超える時刻があれば、その答えは「時刻が合わない」として担当者に回します。

比較表には、1本を1行にして次のように並べます。

尺の列だけは YouTube Data API の値です。 それ以外の列にはAIの値と根拠の時刻が入り、担当者が確かめた列には印が付きます。

月次の報告の下書きは、確かめ終えた比較表だけを Gemini API に渡し、「今月の競合の傾向」「広告主の動画との違い」を、比較表の値だけを根拠に3〜5点で書かせます。 比較表に無いことを書かない、評価や提案を書かない、と指示します。

システムへ連携する

広告主へは、この構成から何も送りません。 報告の下書きは比較表の隣のシートに書き、担当者と上長が直してから、ひな形に貼ります。

APIキーは、プログラムの外の設定に置き、コードに書きません。 YouTube Data API のキーと Gemini API のキーは、別のものにしておきます。

人が確認する

すべての動画の値を、担当者が確かめてから比較表を確定させます。 見る順番を決めておきます。

1. 「時刻が合わない」と other を先に見る … 時刻の場面を開き、値を直すか、other の説明を確かめます
2. 訴求（主）と商品が映る時刻を見る … 報告でいちばん使う値なので、全件の時刻の場面を確かめます
3. 出演者の欄を見る … 名前が入っているものは、画面の文字の時刻を開いて、本当に名前が出ているかを確かめます
4. 報告の下書きを比較表と照らす … 比較表に無いことが書かれていないかを見ます

3番を省かないでください。 人物の名前の誤りは、広告主への報告を通じて社外に出ます。 名前の根拠が画面の文字に無いときは、名前を消して立場だけにします。

目標は、80本をならして1本9分です。 15秒の広告なら、時刻の場面を数か所見るだけで数分です。確かめる場面が多い長めの動画で時間を使います。

担当者が値を直したら、直した軸と直す前の値を記録します。 同じ軸で直しが続くなら、選択肢の言葉があいまいか、選択肢どうしが重なっています。例えば「限定・期間」と「価格・値引き」が同じ動画で取り違えられるなら、どちらを優先するかの決まりを軸のシートに書き、指示にも足します。 直しの記録は、担当者ごとの観点の違いをそろえる材料にもなります。

例外に対処する

1行目と2行目は、YouTube の側の事情で毎月起きます。 広告は配信の期間が終わると非公開にされることがあり、要約した後に見られなくなった動画の値は、比較表に残すかどうかを決めておきます。 この構成では、要約の値（自社が書いた記録）は残し、動画の情報（題名・再生回数など）は次の項のとおり扱います。

記録を残す

• 候補の一覧（動画のID、拾った日、担当者の選別）
• AIに渡した指示と、返ってきたJSON
• 担当者が直した値と、直す前の値
• 確定した比較表と、報告の下書き・確定版
• other の説明の一覧（軸の見直しの材料）

YouTube Data API から取った値の保存には、決まりがあります。 デベロッパーポリシーでは、API から取ったデータの多くについて、保存は30日を超えないこととされ、30日を過ぎたら削除するか取り直すことが求められています。題名や公開日時など、API から取った値は月ごとに取り直し、取り直せないものは消します。 比較表には、動画のIDと、自社が書いた要約の値を残します。

再生回数は、比較表に入れません。 再生回数は広告の配信の量で大きく変わり、中身の比較とは別の話だからです。