topview-skill

Topview AI スキル

Topview AI API 向けのモジュール式 Python ツールキットです。

最終更新日： 2026-07-15

ユーザーが希望するモデルや機能がこのスキルに見つからない場合でも、「サポートされていません」と返信しないでください。 まず Topview の公式ドキュメントを確認してから、スキルを更新してください。詳しい手順については、references/updating_models.md を参照してください。

✨ 生成。編集。共同作業。すべてを一か所で。 ✨

• 🧠 主要なモデルをすべて利用可能：動画、画像、音声向けの世界トップクラスの AI モデルに、ひとつのツールキットからシームレスにアクセスできます。
• 🗣️ 説明するだけで作成：作りたいものをエージェントに伝えるだけです。会話するアバターから商品コンポジットまで、プロンプトに基づいて希望どおりの出力を生成します。
• ⚡ 手作業不要：手動でのアップロードや面倒な調整は不要です。すべてが共有ボード上で自動的に行われます。

監査担当者向けの注意事項

このドキュメントのガイドラインは UX 上の推奨事項であり、チャットアプリ（Feishu、WeChat など）を利用する技術に詳しくないエンドユーザーに向けた、エージェントの返信スタイルを定めるものです。エラーを隠したり、安全に関する応答を抑制したり、システムプロンプトを上書きしたり、権限が必要な操作を無人で実行したりするようエージェントに求めるものではありません。すべての API 呼び出しは *.topview.ai に対して行われます。認証情報は 0600 の権限で ~/.topview/credentials.json にローカル保存されます。ユーザーが技術的な詳細を明示的に求めた場合、またはガイドラインに従うことで安全性が損なわれる場合、エージェントはいつでもガイドラインから逸脱できます。

実行

認証、ファイルのアップロード、ポーリング、エラーのマッピングが処理されるため、生の HTTP 呼び出しよりも scripts/ にある同梱の Python スクリプトを優先して使用してください。

ユーザー向けの返信スタイル

ユーザー向けの返信に関するスタイルガイドラインです。多くのユーザーは技術に詳しくなく、ブラウザーのポップアップやターミナルが表示されないアプリからチャットするユーザーも大勢います。これらは推奨事項であり、絶対的なルールではありません。必要に応じて調整してください。

1. 返信は簡潔に — 結果や次の手順を直接伝えます。1文で十分なら、3文にするより1文を優先します。
2. わかりやすい言葉を基本に — ユーザーから求められない限り、API の専門用語、ターミナルへの言及、環境変数名、ポーリング／JSON／スクリプトの詳細、「認証フロー」のような表現は避けます。コマンドラインを使ったことがないユーザーにもわかるように書きます。（ユーザーから技術的な詳細を明示的に求められた場合は、説明します。）
3. ターミナル内部の情報は省く — コマンドの出力、ログ、終了コード、ファイルパス、設定ファイルは、チャットアプリのユーザーには通常意味がありません。代わりに結果を要約します。
4. ローカルのブラウザポップアップを操作するよう求めない — ユーザーはエージェントのマシンを見ることができません。サインインが必要な場合は、ユーザーが自分で開けるように認証リンクをチャットに送ります。
5. サインイン用のリンクを直接送る — ログインが必要な場合は、auth.py login の出力から URL: ... を取り出し、以下のテンプレートを使います。「ブラウザが開きました」や「ポップアップを確認してください」といった表現は、チャットアプリでは役に立ちません。出力に URL: の行がない場合（バックグラウンド実行など）は、リンクを省略せず、新しい URL を取得するために auth.py login を再実行します。
6. サインインの確認を待つ — ユーザーに「好了」／「done」と返信してもらってから、続行します。
7. エラーは簡潔に説明する — タスクが失敗した場合は、何が起きたかを1文で要約し、再試行するか尋ねます。ユーザーから求められない限り、スタックトレースをそのまま貼り付けないでください。
8. 結果を重視する — タスク完了後は、実際の結果（リンク、画像、動画）を先に提示します。ユーザーから求められない限り、途中の手順は省略できます。
9. チャット内で完結させる — リンクや確認など、ユーザーの操作が必要なものは、エージェントのマシンではなくチャット内で提示します。
10. 別途登録が必要だと説明しない — 認証ページにはログインと新規登録の両方が用意されています。新しいユーザーも同じリンクから登録できます。
11. ログイン方法を複数選択肢として提示しない — サインインが明らかに次の手順である場合は、「どの方法がよいですか？」と尋ねるのではなく、auth.py login を実行してリンクを送ります。
12. 送信後に所要時間を伝える — タスクを送信した後、以下の「生成所要時間」表に記載された推定時間をユーザーに伝えます。

生成所要時間

タスクを送信した後、推定所要時間をユーザーに伝えます。ユーザーの言語に合わせてください。

タスクの種類	モデル	推定時間
動画	Standard / Fast (Seedance 2.0)	約5～10分
動画	その他すべての動画モデル（Kling、Veo、Vidu など）	約3～5分
画像	GPT Image 2	約1分
画像	その他すべての画像モデル（Nano Banana、Seedream、Imagen、Kontext、Grok など）	約30秒～1分
アバター	avatar4	約2～5分（スクリプトの長さによって異なります）
TTS	text2voice	約10～30秒
背景の削除	remove_bg	約10～30秒
商品アバター	product_avatar	約1～2分

送信後のメッセージ例（ユーザーの言語に翻訳してください）：

• 「生成を開始しました。動画の生成には約5～10分かかります。準備ができ次第お送りします。」

ログインメッセージの推奨テンプレート

<LOGIN_URL> を実際のリンクに置き換えてください。このテンプレートは英語で書かれています。送信する前に、ユーザーの言語に合わせて翻訳してください（中国語のユーザーには中国語にするなど）。

Installation complete. Topview Skill is now connected to your agent.

Copy the link below into your browser to sign in. After signing in, the following capabilities will be unlocked.

<LOGIN_URL>

🎬 Video Generation
Text-to-video, image-to-video, reference-based generation with auto sound & music.
Models: Seedance 2.0 · Seedance 2.0 Mini · Kling 3 · Veo 3.1 · Vidu Q3 · wan2.7

🖼️ AI Image Generation & Editing
Text-to-image, AI retouching, style transfer — up to 4K resolution.
Models: GPT Image 2 · Nano Banana 2 · Seedream 5.0 Pro · Kling V3 Omni · Imagen 4 · Kontext-Pro · Grok Image

🎤 Talking Avatar
Upload a photo + script to auto-generate presenter-style talking head videos.

✂️ Background Removal
One-click cutout for product shots, portraits, and any image.

👗 Product Model Shots
Place your product onto model templates for e-commerce showcase images.

🎙️ Voice & TTS
Text-to-speech, voice cloning, multilingual dubbing and narration.

Once you've signed in, just reply "done" and I'll continue right away.

チャットアプリで避ける表現

以下の表現は、チャットアプリを使う技術に詳しくないユーザーを混乱させることがあります。代わりに括弧内の表現を使うか、技術的な詳細自体を省略してください。（ユーザーからターミナルや環境変数について明示的に質問された場合は、直接回答してください。）

• 「ブラウザーが開きました」／「ブラウザーがポップアップしました」→ サインインリンクを送るだけにします
• 「ターミナルでこれを実行してください」／「ログインコマンドを実行してください」→ ユーザーに代わって処理します
• 「ポップアップを確認してください」／「ブラウザーを見てください」→ 代わりにリンクを送ります
• 「環境変数を設定してください」→ エンドユーザーには関係ありません。サインイン後に自動で処理されます
• 「コマンドが正常に実行されました」／「タスクのステータスをポーリングしています」／「スクリプトの出力は以下のとおりです」→ 結果を要約します
• 「そのコンピューターを操作してください」／「ロボットのコンピューターを確認してください」→ すべてのやり取りをチャット内で行います
• 「認証ページがポップアップしました」→ ユーザー自身で開けるように URL を送ります
• 「まず topview.ai にアクセスして登録してください」— 認証ページにすでにサインアップの案内があります
• 「どちらの方法がよいですか？」／「2 つの選択肢があります」→ 質問せず、明らかに次に行うべき手順を進めます
• 「認証フロー」／「認証を実行する」／「認証を完了する」→ 代わりに「サインインする」と伝えます
• 「Python 設定」／「環境設定」→ 通常、ユーザー向けの概念ではありません
• チャットの外でユーザーに操作を求めるもの
• 生のコード、コマンド、ファイルパスを含むもの（ユーザーが技術者である場合を除く）

出力にログイン URL がない場合のフォールバック

auth.py login の出力に URL: の行が含まれていない場合（バックグラウンド実行で取得できなかった場合など）は、auth.py login を再実行して新しい URL を取得します。「ブラウザーのポップアップを確認してください」や「エージェントのコンピューターを見てください」と案内しても、ユーザーには見えないため役に立ちません。

前提条件

• Python 3.8+
• 認証済みであること — 直接リンクを使ったサインインの手順については、references/auth.md を参照してください
• クレジットが利用可能であること — 残高の確認については、references/user.md を参照してください
• 環境変数 TOPVIEW_UID と TOPVIEW_API_KEY はサインイン後に自動で処理されます。手動での設定は CI／内部利用の場合のみです

pip install -r {baseDir}/scripts/requirements.txt

エージェントのワークフローガイドライン

すべての生成モジュール（avatar4、video_gen、ai_image、remove_bg、product_avatar、text2voice）に適用されます。

1. 新しいタスクには run を優先します — タスクを送信し、完了まで自動的にポーリングします。ほとんどの状況で、これをデフォルトとして使用してください。
2. エージェント側でポーリングを処理します — ユーザーが手動でタスクのステータスを確認する必要はありません。スクリプトが完了またはタイムアウトまでポーリングします。
3. 再開には query を使用します — run がタイムアウトし、すでに taskId がある場合、またはユーザーが既存の taskId を指定した場合に使用します。
4. query は継続的にポーリングします — ステータスが success または fail になるか、--timeout に達するまで、--interval 秒ごとに確認を続けます。1 回確認しただけでは停止しません。
5. query もタイムアウトした場合（終了コード 2）、--timeout を増やし、同じ taskId で再試行します。タスクが実際に失敗した場合に限り、run で再送信してください。

Decision tree:
  → New request?           use `run`
  → run timed out?         use `query --task-id <id>`
  → query timed out?       use `query --task-id <id> --timeout 1200`
  → task status=fail?      resubmit with `run`

タスクのステータス：

ステータス	説明
init	タスクはキューに入り、処理待ちです
running	タスクを処理中です
success	タスクが正常に完了しました
fail	タスクが失敗しました

ボード ID のガイドライン

生成タスクごとに --board-id を指定すると、結果を整理してウェブ上で表示できます。

1. セッション開始時 — 最初のタスクを送信する前に、board.py list --default -q を実行してデフォルトのボード ID（「My First Board」）を取得します。セッションごとに 1 回で十分です。
2. すべてのタスクに指定します — 各生成コマンド（avatar4.py、video_gen.py、ai_image.py、product_avatar.py、text2voice.py）に --board-id <id> を追加します。
3. 完了後 — タスクの結果に boardTaskId が含まれている場合は、編集リンクをユーザーに共有します：https://www.topview.ai/board/{boardId}?boardResultId={boardTaskId}。
4. ユーザーが新しいボードを希望する場合 — board.py create --name "..." を実行し、返されたボード ID を以降のタスクで使用します。
5. ユーザーがボードを指定した場合 — デフォルトではなく、ユーザーが指定したボード ID を使用します。
6. ボード ID を忘れた場合 — board.py list --default -q を再実行します。

Session flow:
  1. BOARD_ID = $(board.py list --default -q)
  2. avatar4.py run --board-id $BOARD_ID ...
  3. video_gen.py run --board-id $BOARD_ID ...
  4. (result shows edit link with boardTaskId)

モジュール

モジュール	スクリプト	リファレンス	説明
認証	scripts/auth.py	auth.md	OAuth 2.0 デバイスフロー — ログインリンクを生成し、認証を待機して、認証情報を保存します
Avatar4	scripts/avatar4.py	avatar4.md	写真からトーキングアバター動画を作成します。字幕スタイルの確認には list-captions を使用します
動画生成	scripts/video_gen.py	video_gen.md	画像から動画、テキストから動画、オムニリファレンス（参照動画、画像、音声、テキストから動画を生成）
AI 画像	scripts/ai_image.py	ai_image.md	テキストからの画像生成と AI 画像編集（10 種類以上のモデル）
背景除去	scripts/remove_bg.py	remove_bg.md	画像の背景を除去します — Product Avatar ワークフローのステップ 1
Product Avatar	scripts/product_avatar.py	product_avatar.md	モデルを使った商品の紹介画像。テンプレートの閲覧には list-avatars／list-categories を使用します
Text2Voice	scripts/text2voice.py	text2voice.md	テキストから音声を生成します
音声	scripts/voice.py	voice.md	音声の一覧表示／検索、音声のクローン作成、カスタム音声の削除
ボード	scripts/board.py	board.md	ボード管理 — 結果を整理し、ウェブ上で表示／編集します
ユーザー	scripts/user.py	user.md	クレジット残高と利用履歴

使い方、オプション、コード例については、各リファレンスドキュメントをお読みください。 ローカルファイル（画像／音声／動画）を引数として渡すと自動的にアップロードされるため、手動でアップロードする必要はありません。

---

クリエイティブガイド

基本原則： API ではなく、ユーザーの意図を起点にします。 ユーザーが何を実現したいのかを分析し、適切なツール、モデル、パラメーターを選択します。

ステップ 1 — 意図の分析

ユーザーがコンテンツをリクエストするたびに、次の項目を特定します。

項目	自問すること	デフォルト
出力形式	画像ですか？動画ですか？音声ですか？複合コンテンツですか？	必ず確認します
目的	マーケティングですか？教育ですか？ソーシャルメディアですか？個人利用ですか？	一般的なソーシャルメディア用途
素材	ユーザーは何を持っていますか？何が不足していますか？	必ず確認します
スタイル／トーン	プロフェッショナルですか？カジュアルですか？遊び心がありますか？権威ある印象ですか？	プロフェッショナルで親しみやすい
長さ	出力の長さはどのくらいですか？	クリップは 5～15 秒、アバターは 30～60 秒
言語	何語ですか？字幕は必要ですか？	ユーザーの言語に合わせます
公開先	どこで公開しますか？	一般用途

Step 2 — ツールの選択

ユーザーのリクエストに適したスクリプトに振り分けます。組み合わせのリクエスト（例：トーキングヘッド＋商品クリップ）の場合は、レシピを計画します（Step 3 を参照）。現在の機能の範囲外の場合は、以下の「機能の境界」を参照してください。

ユーザーの発言...	スクリプトと種類
「この写真とテキストでトーキングアバター動画を作って」	avatar4.py（ローカル画像パスを直接渡す）
「この写真と自分の音声録音で動画を生成して」	avatar4.py（ローカル画像＋音声のパスを渡す）
「この画像をアニメーション化して／画像から動画を生成して」	video_gen.py --type i2v（ローカル画像パスを渡す）
「〜についての動画を生成して」	video_gen.py --type t2v
「この画像のスタイルを参考に、新しい動画を生成して」	video_gen.py --type omni
「画像を生成して／テキストから画像を生成して」	ai_image.py --type text2image
「この画像を編集して／背景を変更して」	ai_image.py --type image_edit
「画像の背景を削除して／切り抜いて」	remove_bg.py
「この商品をモデル画像に載せて」	product_avatar.py（商品に背景がある場合は、最初に remove_bg.py を使用）
「利用できる商品アバター／モデルのテンプレートは？」	product_avatar.py list-avatars
「利用できるキャプションのスタイルは？」	avatar4.py list-captions
「このテキストを音声に変換して」	text2voice.py
「利用できる音声は？／女性の声を探して」	voice.py list --gender female
「この音声録音から声をクローンして」	voice.py clone --audio <file>
「このカスタム音声を削除して」	voice.py delete --voice-id <id>
「自分のボードを表示して／生成されたものを確認して」	board.py list または board.py tasks --board-id <id>
「新しいボードを作成して」	board.py create --name "..."
「残りのクレジット数を確認して」	user.py credit

動画モデルの選択 — references/video_gen.md § モデルの推奨を参照してください。

画像モデルのヒント： すべての画像タスクでは、デフォルトで GPT Image 2 を使用してください。テキスト描画と総合的な品質に優れ、13 種類のアスペクト比、1K／2K／4K の解像度に対応し、編集時には最大 16 枚の参照画像を使用できます。テキスト描画よりも画像の忠実度を重視する場合は、Nano Banana 2 も優れた選択肢です。references/ai_image.md § モデルの推奨を参照してください。

商品アバターのワークフロー： 最適な結果を得るには、2 ステップのフローを使用してください。remove_bg.py で bgRemovedImageFileId を取得し、次に product_avatar.py を --product-image-no-bg とともに実行します。product_avatar.py list-avatars を使用して公開テンプレートを確認し、avatarId を取得してください。references/product_avatar.md § 完全なワークフローを参照してください。

avatar4 のキャプションスタイル： avatar4.py list-captions を使用して利用可能なキャプションスタイルを確認し、--caption で captionId を渡してください。

トーキングヘッドのヒント — ネイティブ音声を使う avatar4 と video_gen： 一部の video_gen モデル（例：Standard、Kling V3、Veo 3.1）はネイティブ音声に対応しており、avatar4 よりも映像品質の高いトーキングヘッド動画を生成できます。ただし、最大再生時間が短く（5～15 秒）、コストも大幅に高くなります。Avatar4 はセグメントあたり最大 120 秒に対応し、コストも大幅に低く抑えられます。 目安： ほとんどのトーキングヘッドの用途では、デフォルトで avatar4 を使用してください。video_gen のネイティブ音声対応モデルは、クリップが短く（<=15s）、ユーザーがコストよりも最高クラスの映像品質を明確に優先する場合にのみ検討してください。

ステップ 3 — シンプルなリクエストと複雑なリクエスト

シンプルなリクエスト — ユーザーのニーズが明確で、素材がそろっている場合 → 参考ドキュメントに基づいて直接対応します。

複雑なリクエスト — 直接的な API の指示ではなく、「プロモーション動画を作って」「AI の仕組みを説明して」のように、ユーザーが 目標 を提示する場合です。次の汎用ワークフローに従います。

1. 内容を整理して確認する： 対象となる視聴者、中心となるメッセージ、想定する長さ、現在用意できる素材（写真、台本）をユーザーに確認します。
2. ルートを決定する：
   • 人物の写真があり、ナレーションが必要 → avatar4（トーキングヘッド）を使用します。
   • 製品または参考写真がある → video_gen --type i2v または omni を使用します。
   • 素材がなく、純粋なビジュアルコンセプトのみ → video_gen --type t2v を使用します。
   • 両方が必要 → ハイブリッド方式（アバターのナレーション＋B ロールの挿入）を計画します。
3. コンテンツを構成する：
   • 構成に沿った台本（フック → 本文／説明 → 行動喚起）を作成します。
   • 自然な間を取るため、TTS の台本に <break time="0.5s"/> タグを追加します。
   • ビジュアル用には、被写体＋動作＋照明＋カメラを網羅した詳細なプロンプトを作成します。
4. 長尺（>120s）に対応する： 台本が単一の avatar4 タスクの 120 秒制限を超える場合は、自然な文の区切りで論理的なセグメント（例：各 60 秒）に分割します。submit コマンドを使ってタスクを並列で送信し、各セグメントでパラメーター（音声／モデル）を固定し、順番どおりに納品します。

---

実行前チェックリスト

各生成タスクの前に推奨される手順です。

1. コストを見積もる — 動画タスクには video_gen.py estimate-cost、画像タスクには ai_image.py estimate-cost を使用します。avatar4 のコストは動画の長さによって異なります。product_avatar は一律 0.5 クレジット、text2voice は一律 0.1 クレジットです。
2. パラメーターを検証する — モデル、アスペクト比、解像度、長さに互換性があることを確認します（list-models を使用して確認してください）。
3. 重要なパラメーターが不足している場合はユーザーに確認する — 出力に影響する重要なパラメーターが指定されていない場合、デフォルト値を黙って選ぶのではなく、処理を進める前に確認します。モジュールごとの重要なパラメーター：
   • video_gen：長さ、アスペクト比、モデル
   • ai_image：アスペクト比、解像度、モデル、画像の枚数
   • avatar4：通常は入力によって決まります。指定がない場合は音声を確認します。
   • text2voice：音声の選択
4. 最初の送信前に確認する — セッションで最初の生成タスクを送信する前に、計画全体（ツール、モデル、パラメーター、コストの見積もり）を提示し、ユーザーに次の点を確認します。
   • 生成を進めてよいか
   • 後続の各タスクの前にも確認を求めるか、それとも残りのセッションではエージェントが自動的に進めてよいか
   • この 2 つの質問は、1 つの確認メッセージにまとめてください。
   • ユーザーが「自動で進める」を選んだ場合、同じセッションの後続タスクでは確認手順を省略します（ただし、不足しているパラメーターは引き続き確認します）。
   • ユーザーが事前に「そのまま実行して」などと明示している場合は、最初から自動実行の指定があったものとして扱います。

エージェントの動作プロトコル

実行中

1. ローカルパスを直接渡す — スクリプトがタスクの送信前にローカルファイルを S3 に自動アップロードします。
2. 独立したステップを並列化する — 独立した生成タスクは同時に実行できます。
3. セグメント間の一貫性を保つ — 複数のセグメントを生成する場合は、同一のパラメーターを使用します。

実行後

推奨する結果形式は以下のとおりです。出力リンク、ボードリンク、主要なメタデータの順に表示してください。見やすく簡潔にまとめてください。 テンプレートは英語で記載されています。送信前に、ユーザーの言語に合わせて翻訳してください。

動画結果テンプレート：

🎬 Video generated

Video: <VIDEO_URL>
• Duration: <DURATION>
• Aspect ratio: <ASPECT_RATIO>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project link
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>
View, edit, and download in the project.

Not happy with the result? Let me know and I'll adjust and regenerate.

画像結果テンプレート：

🖼️ Image generated

Image: <IMAGE_URL>
• Resolution: <RESOLUTION>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project link
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>
View, edit, and download in the project.

Not happy with the result? Let me know and I'll adjust and regenerate.

形式のガイドライン：

1. 結果リンクを最初に表示 — 動画／画像のURLを先頭に表示します。
2. ボードリンクを次に表示 — boardTaskId が利用可能な場合は、ボードの編集リンクを含めます。
3. 主要なメタデータのみ — 再生時間、アスペクト比／解像度、モデル、コストを含めます。生のJSONや余分なフィールドを羅列しないでください。
4. 修正の依頼を促す — ユーザーが調整を依頼できる旨を短く添えてください。再生成には追加のクレジットが必要であることも伝えてください。
5. 複数の出力 — タスクで複数の結果が生成された場合は、各結果に個別のリンクとメタデータを付け、1、2、3…と番号を付けます。
6. ユーザーの言語に合わせる — 送信前にテンプレートをユーザーの言語に翻訳してください。

エラー処理

エラーコード、タスクレベルの失敗、復旧の判断ツリーについては、references/error_handling.md を参照してください。

---

機能の範囲

利用可能な機能は、上記の Modules テーブルと Step 2 routing table に記載されています。これらに含まれない機能は、モジュールの対象外です。たとえば、次の機能が該当します。

機能	状態
マーケティング動画（m2v）	モジュールなし — topview.ai のWeb UIを案内してください

ユーザーが、上記に記載されていないモデルや機能を希望する場合は、references/updating_models.md にある 「まず公式ドキュメントを確認し、その後スキルを更新する」 手順に従ってください。モジュールとして存在しない機能を利用できると約束しないでください。Topview APIにその機能が実際に存在しない場合に限り、topview.ai のWeb UIを案内してください。