byted-airesearch-videoeval

Byted Airesearch Videoeval

このスキルは、時間のかかる素材評価タスクの送信と照会に使用します。

使用する場合

ユーザーが次のことを希望している場合に、このスキルを使用します。

• 動画素材またはクリエイティブアセットを評価する
• 素材評価タスクを送信し、タスク識別子を取得する
• 既存の評価タスクのステータスを後で確認する
• 以前に作成した評価タスクの最終的な詳細または結果を取得する

一般的な動画アップロードのリクエストには、このスキルを使用しないでください。

現在のワークフロー

1. アップロードを開始する前に、入力バッチ全体を検証します。
2. ローカルの動画ファイルをアップロードし、返された attachment_id の値を取得します。
3. アップロードした添付ファイル ID を指定してタスクを作成します。
4. タスクの作成後、すぐに成功を返します。
5. 進捗や結果を確認したい場合は、後でタスクリストまたはタスク詳細を照会するようユーザーに案内します。

このワークフローは、意図的に非同期で進行します。タスク作成後に自動でポーリングしないでください。

必須の動作

• アップロード API を、ユーザー向けの独立した機能として公開しないでください。
• 「この動画をアップロードして」「このファイルを保存して」「この動画を送って」などの一般的なリクエストで、このスキルを実行しないでください。
• ユーザーが新しい素材評価タスクの作成を明示的に意図している場合にのみ、アップロード API を呼び出してください。
• 新しいタスクを作成する場合は、検証、アップロード、タスク作成を一貫したフローで実行できる scripts/submit_evaluation_task.py を優先してください。
• scripts/upload_video.py はオーケストレーションフローで使用する内部ヘルパーとして扱い、ユーザーが最初に実行するスクリプトとして扱わないでください。このスクリプトは、内部オーケストレーション用マーカーを付けて呼び出さない限り、直接の使用を拒否します。

複数ファイルを送信する場合は、最初のアップロードを開始する前にバッチ全体を検証できるよう、オーケストレーション用のエントリーポイントを使用してください。

送信上限

• 1 つのタスクに含められる動画は最大 10 本です。
• 有効化されていないユーザーには、直近 24 時間以内に送信できる動画数に、繰り越し型の無料枠として最大 10 本の上限があります。
• 新しいタスクの動画数は、直近 24 時間以内にすでに送信された動画数に加算されます。合計が 10 本を超える場合、サービスはタスクを拒否し、アクセスを有効化するため Volcengine の営業担当者に連絡するようユーザーに案内します。
• 有効化済みのユーザーには、この繰り越し型の 24 時間無料枠の制限は適用されません。
• 枠の計算は、重複排除を行わず、タスクごとに実際に送信された動画数に基づきます。
• 直近 24 時間以内に作成されたタスクは、実行中のタスクを含め、すべて繰り越し枠の対象になります。
• ログインベースのアクセスと API キーによるアクセスは、同じ枠を共有します。
• このスキルは、アップロード開始前にタスクごとの上限をローカルで適用します。繰り越し型の 24 時間枠はサービス側で適用されるため、サービスから拒否された場合は、明確な説明を添えてユーザーに伝えてください。

認証

現在の API は API キー認証を使用します。

このスキルが送信するすべての API リクエストに、次のヘッダーを含める必要があります。

• x-product-version: 20
• Authorization: bearer {API_KEY}

推奨する入力方法：

• --api-key "<api-key>"
• BYTED_AIRESEARCH_VIDEOEVAL_API_KEY

API キーが利用できない場合は、次の場所で作成または確認するようユーザーに案内してください。

• https://console.volcengine.com/datatester/ai-research/audience/list?tab=apikey

その後、API を呼び出す前に API キーを提供するようユーザーに依頼してください。

API キーが指定されていない場合、スクリプトは直ちに失敗し、上記の API キーページを案内する明確なエラーを表示する必要があります。

既知の API 対応範囲

添付ファイルのアップロード

• エンドポイント：POST https://console.volcengine.com/datatester/compass/api/v3/survey/attachment
• リクエスト：multipart/form-data
• ファイルフィールド：file
• アップロード制約：
  • 1 回のアップロードリクエストには動画ファイルをちょうど 1 つ含める必要があります
  • 各動画のサイズは 50MB 以下である必要があります
  • ファイル形式は mp4 である必要があります
  • MIME タイプは video/mp4 である必要があります
• 出力のマッピング：
  • 添付ファイルのペイロードを未加工のまま保持します
  • 添付ファイルオブジェクトの id フィールドを attachment_id に割り当てます

upload_video.py スクリプトは、タスク作成ワークフローで使用する内部ヘルパーです。ユーザー向けの主要なエントリーポイントではありません。

タスクの作成

• エンドポイント：POST https://console.volcengine.com/datatester/compass/api/v3/survey/task
• 固定リクエストフィールド：
  • form_id: 0
  • agent_id: 125
  • audience_id: 3664529
• 現在公開されている任意のリクエストフィールド：
  • prompt
  • language
  • is_typical_user_enabled
  • typical_user_count
  • typical_user_selection_mode
  • is_report_enabled
  • attachment_ids
• 作成時の制約：
  • 1 回のタスク送信に含められる動画は最大 10 件です
  • 1 回のリクエストに含められる attachment_ids は最大 10 件です

作成時には、複数の添付ファイル ID が明示的に指定されていない限り、アップロードした attachment_id を 1 件の要素を持つ attachment_ids 配列として送信してください。

一覧と詳細

タスク詳細は接続済みで、既存のタスクを直接照会できます。

• エンドポイント：GET https://console.volcengine.com/datatester/compass/api/v3/survey/task/{id}
• 現在の認証方式：API キーのベアラートークン
• 出力のマッピング：
  • タスクオブジェクトの id フィールドを task_id にマッピングします
  • タスクオブジェクトの status フィールドを task_status にマッピングします
  • task.detail を解析します
  • key == video_structured_result かつ sub_tab != null の項目のみを保持します
  • 後続のエージェントで使用するコンパクトな summary ブロックを公開します

タスク一覧は接続済みで、既存のタスクを直接照会できます。

• エンドポイント：GET https://console.volcengine.com/datatester/compass/api/v3/survey/task
• 現在の認証方式：API キーのベアラートークン
• 現在の固定クエリパラメーター：
  • page=1
  • page_size=100
  • agent_id=125
• 出力のマッピング：
  • 各タスク項目を task_id、name、status、created_at、updated_at にマッピングします
  • ページネーション情報を data.page に保持します

コマンド

# Validate a whole batch before upload, then upload all files and create the task
python scripts/submit_evaluation_task.py \
  --file /path/to/video-1.mp4 \
  --file /path/to/video-2.mp4 \
  --api-key "<api-key>"

# Single-video create flow
python scripts/submit_evaluation_task.py \
  --file /path/to/video.mp4 \
  --prompt "Evaluate this material for audience fit and content quality." \
  --api-key "<api-key>"

# Query task list later
python scripts/list_evaluation_tasks.py

# Query task detail later
python scripts/get_evaluation_task_detail.py --task-id 12345

レスポンスの処理

すべてのスクリプトは、同じトップレベルのエンベロープを持つ JSON を標準出力に出力します。

• status
• message
• request_id
• data
• error

重要な正規化済みフィールド：

• タスク送信：data.task_id、data.task_status、data.submitted_video_count
• 一覧：data.items
• 詳細：data.detail、data.summary

最終回答のルール

• 詳細エンドポイントから返される構造化 JSON を、内部的な信頼できる情報源として使用してください。
• 最終回答は、人が読みやすい自然な言葉で提示してください。
• タスクが完了したら、生データをそのまま出力するのではなく、簡潔なレポート形式の回答を優先してください。
• 生の JSON をユーザーに出力しないでください。
• video_eval、video_user_report、distribution、field_desc など、実装に関する内部フィールド名を公開しないでください。
• タスク一覧のレスポンスにも同じルールを適用してください。一覧結果は内部的な情報源として使用し、生のフィールドではなく自然な言葉で要約して提示してください。
• タスク一覧への回答では、ユーザーが詳細を後から照会するタスクを選びやすくするため、タスク ID、タスク名、ステータス、作成日時、更新日時を、人が読みやすい文章に含めてもかまいません。
• 動画が複数ある場合は、動画ごとに分けて要約してください。
• 完了したタスクの詳細結果は、タスクの結論、動画ごとの短いセクション、元データが裏付けている場合は全体的な推奨事項という、読みやすいレポート形式を優先してください。
• タスクがまだ完了していない場合は、レポートを捏造しないでください。現在のステータスを明確に伝え、後でもう一度確認するようユーザーに依頼してください。
• ユーザーが生の構造化データを明示的に求めた場合にのみ、生データを提示してください。

実践的なガイダンス

• 新規に送信する場合は、アップロードを独立した手順としてユーザーに提示するのではなく、オーケストレーションのフローを使用してください。
• アップロード前にローカルファイルを検証してください。MP4 以外のファイル、MIME タイプが video/mp4 ではないファイル、またはサイズが 50MB を超えるファイルは、具体的で対処方法がわかるエラーメッセージを表示して拒否してください。
• API を呼び出す前に、タスク作成時の入力を検証してください。添付ファイル ID が 10 個を超えるリクエストは、具体的で対処方法がわかるエラーメッセージを表示して拒否してください。
• 複数の動画を一括送信するフローでは、アップロードを開始する前にバッチ全体のサイズを検証してください。バッチに 10 個を超えるファイルが含まれている場合は、直ちに失敗させ、何もアップロードしないでください。
• 直近 24 時間の無料枠を超過したためにサービスがタスクの作成を拒否した場合は、ユーザー向けメッセージに次の標準的な中国語の文言を使用してください：免费版用户每24小时最多提交10个评估视频，如需购买请联系火山引擎销售人员
• 作成が成功した後、タスクは正常に送信され、後から確認できることをユーザーに伝えてください。
• ユーザーが過去のタスクを閲覧または検索したい場合は、タスクリストを使用してください。
• ユーザーがすでにタスク ID を把握しており、最終結果を確認したい場合は、タスクの詳細を使用してください。