Agent-Media UGC Playbook

Agent-Media UGC プレイブック

agent-media で完成した UGC 動画を作成する必要があるエージェント（Claude、Cursor、カスタム）です。ツールは make_ugc（Agent-Media UGC Video）の1つだけです。サブスキルを選ぶ必要はありません。make_ugc が内部でアイデンティティを解決し、パイプライン全体を実行します。

1つのツール、3つの使い方

作りたいもの	make_ugc に渡すもの	結果
短いクリップ	1行の script（＋任意で人物／画像／キャラクター）	すっきりしたトークヘッドクリップ
長いモノローグ	長い script（＋image または character で実在の顔を指定）	トリミングされない、シームレスな複数テイク動画
ナレーション付き B ロールレビュー	script ＋ broll_url ＋ character／image	映像に重ねて人物がナレーションする動画

呼び出し方

呼び出しは1回だけです。サーバーがパイプライン、テイク数、長さを選び、1つの Temporal ワークフローで実行した後、ポーリングする skill_run_id を返します。

POST https://api.agent-media.ai/v1/skills/make_ugc/run
Authorization: Bearer $AGENT_MEDIA_API_KEY

{
  "script": "Okay this is wild, I tried the new flow and it actually works.",
  "person": "a friendly young woman, soft daylight, candid framing",
  "name": "Maya, 27"
}

status が succeeded になるまで GET /v1/skills/runs/<skill_run_id> でポーリングします。final_output.video_url が完成した MP4 です。

すべてのフィールドについては、skills/make-ugc/SKILL.md を参照してください。

ステップ D — 公開する（任意）

video_url を取得したら、publish-to-social スキルを使って、ユーザーの TikTok／Instagram／X に直接投稿できます。POST /v1/social/publish（CLI agent-media social publish、MCP social_publish）を使用します。ユーザーは OAuth（/v1/social/connect）で各ネットワークに一度接続します。skills/publish-to-social/SKILL.md を参照してください。

アイデンティティ

• person — 言葉で人物を説明します。image — 写真（https URL または base64）です。character — 保存済みの char_… ID、または list_characters で取得した character_sheet_url です。3つとも省略すると、デフォルトの人物が使われます。
• 長いモノローグや B ロールレビューでは実在の顔が必要です。person だけでなく、image または character を渡してください。
• 保存済みのキャラクターを再利用するには、次の呼び出しでも同じ character を渡します。再生成は不要です。

ルール

• make_ugc がスクリプトのペース配分と分割を行います。セリフやモノローグの全文を渡し、トリミングしないでください。長さはスクリプトから推定されます。
• 渡す画像／動画の URL は、公開された https URL である必要があります（make_ugc が R2 に再ホストします）。保存済みキャラクターの場合は character_sheet_url または char_… を指定できます。
• クレジットは各テイクの実行時に差し引かれます。動画内のポートレートとキャラクターシートの準備は無料です。支払いが発生するのは動画自体のみです。
• 説明に「selfie」や「phone」を入れないでください。代わりに「カメラに向かって話す」と指定してください。make_ugc が内部で処理します。

トラブルシューティング

• INSUFFICIENT_CREDITS — ユーザーのクレジットが不足しています。agent-media.ai の請求ページへのリンクを案内してください。
• make_ugc_needs_face — 長いモノローグや B ロールレビューには、person だけでなく、image または character（実在の顔）が必要です。
• 動画の被写体がスマートフォンを持っている — 「selfie」または「phone」に言及するポーズのヒントが使われています。それを削除するか、pose: "" を設定してください。
• ステップが submitted のまま止まっている — Temporal ワーカーが再起動中の可能性があります。30秒待ってから再度ポーリングしてください。それでも5分後に止まったままの場合、ワークフローが停止しています。workflow_id を添えて agent-media サポートにお問い合わせください。

関連項目

• reference/auth.md — 初回セットアップ
• reference/pacing.md — 例を含む、1秒あたり2〜4語のルール
• reference/realism-rubric.md — すべてのプロンプトに組み込まれている9つのリアリズム要素