narrator-ai-cli

narrator-ai-cli — AI 動画ナレーション CLI スキル

Narrator AI の動画ナレーション API 用 CLI クライアントです。AI エージェントと開発者向けに設計されています。

• CLI リポジトリ: https://github.com/NarratorAI-Studio/narrator-ai-cli
• リソースのプレビュー（BGM／吹き替え／テンプレート）: https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc

参照インデックス

このファイルでは、判断フロー、一般的なワークフロー、参照先を説明します。詳細な参照情報は references/ にあります。

トピック	ファイル
リソースの選択（素材／BGM／吹き替え／テンプレート）— 一覧表示コマンド、レスポンス形式、フィールドの対応付け	references/resources.md
パラメーター表と JSON の例を含むワークフローの全手順（Fast Path ＋ Standard Path）	references/workflows.md
Magic Video — 任意のビジュアルテンプレート手順（カタログ、パラメーター、言語ルール）	references/magic-video.md
ポーリングパターン、タスクの種類、ファイル操作、ユーザーアカウント、エラーコード	references/operations.md

パイプラインの概要

                    ┌─── Fast Path (原创文案, cheaper) ───┐
                    │   fast-writing → fast-clip-data     │
  Source material ──┤              ↓                      ├──→ video-composing ──→ (magic-video)
  (material list /  │   [video-composing keys off         │   final MP4 URL       optional visual
   search-movie /   │    fast-clip-data.task_order_num]   │                        template pass
   file upload)     └─────────────────────────────────────┘
                    ┌─── Standard Path (二创文案) ────────┐
                    │   popular-learning → generate-      │
                    │   writing → clip-data               │
                    │              ↓                      │
                    │   [video-composing keys off         │
                    │    generate-writing.task_order_num] │
                    └─────────────────────────────────────┘

エージェントのルール（必須 — すべての手順に適用）

必ず行うこと：

• 操作の前に確認します。 すべてのリソース（ソース、BGM、吹き替え、テンプレート）と、すべての magic-video の送信には、ユーザーの明示的な承認が必要です。自動選択、自動送信は決して行いません。
• データを参照し、創作しません。 material list のフィールドまたは task search-movie の出力から confirmed_movie_json を構築します。どちらからも取得できない場合は、ユーザーに確認し、捏造しないでください。
• 言語の連鎖を守ります。 吹き替え音声の言語によって、文章作成タスクの language パラメーターと、すべての magic-video のテキストパラメーターが決まります。3つすべてを一致させてください。→ references/magic-video.md § 言語の認識
• material list は最後までページネーションし、プログラムで検索します。 total の件数に達するまで全ページを取得してから、JSON に対して grep -i または python3 -c を実行します。端末の表示が途中で切れている可能性があるため、決してそのまま信用しないでください。
• 標準の while ループを使い、5秒間隔でポーリングします。 固定回数の for ループは決して使いません。→ references/operations.md § タスクのポーリング

決して行わないこと：

• リクエスト本文全体（テンプレートとすべての template_params 値）を提示してユーザーの確認を得ることなく、magic-video を送信しないでください。 費用は1分あたり30ポイントで、取り消せません。
• ナレーション言語が中国語以外の場合、magic-video のテキストパラメーターに中国語のデフォルト値を送信しないでください。 デフォルト値は中国語でハードコードされているため、中国語以外の動画にも中国語のテキストが表示されます。
• .task_id（32文字の16進数）を order_num として送信しないでください。 後続タスクで必要なのは .task_id ではなく .task_order_num（generate_writing_xxxxx のような接頭辞付き文字列）です。16進数を送信すると 10001 任务关联记录数据异常 が返されます。見た目が似ているもう1つの値、.results.order_info.order_num（script_xxxxx）も誤りです。references/operations.md § タスククエリのレスポンス形式を参照してください。
• 失敗後にパスを自動で切り替えないでください。 手順が失敗した場合は、エラーをユーザーに提示し、同じパスを再試行するか、もう一方のパスに切り替えるか、中止するかを明示的に確認してください。エージェントの判断でパスを切り替えてはいけません。

前提条件

このスキルでは、narrator-ai-cli バイナリがインストールされ、有効な NARRATOR_APP_KEY で設定されていることを前提とします。インストール／セットアップについては README.md を参照してください。エージェントは narrator-ai-cli user balance を実行して確認できます。

基本概念

概念	説明
file_id	アップロード済みファイルの32文字の16進数文字列です。file upload またはタスクの結果から取得します
task_id	タスクの作成時に返される32文字の16進数文字列です。task query でポーリングします
task_order_num	タスクの作成後に割り当てられます。後続タスクの order_num として使用します
files[]	完了したタスクのレスポンスに含まれる出力ファイル（トップレベルのフラットな配列）です。各エントリには file_id、file_path、suffix があります。次の手順の入力として .files[0].file_id を読み取ります
learning_model_id	ナレーションスタイルモデルです。事前作成済みテンプレート（90種類以上）または popular-learning の結果から取得します
learning_srt	参照用 SRT の file_id です。learning_model_id と同時には使用できません

会話の開始

⚠️ エージェントの動作 — セッションの最初のメッセージ：映画のタイトルやワークフローのパスをユーザーに尋ねる前に、このスキルでできることを先に案内してください。多くのユーザーは、自分の動画と SRT をアップロードする必要があると思い込んでおり、スキルにあらかじめ用意された素材ライブラリが含まれていることに気づいていません。この手順を省くと、不要なアップロードやセッションの中断につながることがよくあります。

最初に必ず伝えること（会話の言語に合わせて調整してください）：

1. 最初に、あらかじめ用意された素材ライブラリを案内します。 動画と SRT がすでに読み込まれた、すぐに使える映画が約 100 作品あり、ほとんどの場合アップロードは不要だと最初に伝えてください。
2. 具体的な開始方法を 3 つ提示します（ユーザーに選んでもらいます）。
   • 「使いたい映画が決まっています」→ タイトルを聞き、まず素材を検索します。見つからない場合に限り、task search-movie を実行します
   • 「利用できる素材を見せてください」→ material list --json を実行し、さまざまなジャンルから 5～8 作品を紹介します。希望があればジャンルで絞り込めると伝えます
   • 「自分の動画と SRT をアップロードします」→ file upload を案内します
3. Fast と Standard のどちらにするかは、素材が決まるまで尋ねないでください。 一度に両方を尋ねると、ユーザーはまだ判断材料がないのに選択を迫られてしまいます。
4. 必要に応じて、ビジュアルリソースのプレビューリンク（BGM／吹き替え／テンプレートを視覚的に閲覧できます）を共有できます：https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc — ただし、ユーザーが閲覧を希望した場合に限り、最初からリンクを大量に提示しないでください。

最初のメッセージの例（中国語での会話）：

你好，欢迎使用 AI 解说大师。这个技能可以帮你生成电影/短剧解说视频。我这边内置了约 100 部电影素材（视频 + 字幕都是现成的），所以大多数情况你不需要自己上传任何文件。

你想怎么开始？

1. 直接告诉我片名 — 我先查内置素材库，没有再去外部搜
2. 让我列一些内置素材 — 你可以按类型挑（喜剧 / 动作 / 悬疑 / 科幻…）
3. 自己上传视频 + 字幕 — 我引导你完成上传流程

素材が確定したら、以下の選択手順に沿って、1 回のターンにつき 1 つの質問だけを、順番にユーザーに確認してください。複数の選択肢を 1 つのメッセージにまとめないでください。パスを選ぶ前に target_mode について考えることはできません。

選択手順（各ステップで、ユーザーの明確な確認を待ちます）：

1. 素材 — 上記で確認済みです。
2. ワークフローパス — Fast（オリジナル原稿）または Standard（二次創作原稿）。以下の「2 つのワークフローパス」を参照してください。
3. target_mode — パスが Fast の場合にのみ尋ねます。モード 1／2／3 から選びます（以下の「Fast Path 内部：target_mode」を参照）。パスが Standard の場合は、この質問を完全に省略してください。Standard Path には target_mode がありません。
4. BGM → 吹き替え音声 → ナレーションテンプレート — 「リソース選択プロトコル」を参照してください。

⚠️ アンチパターン（絶対にしないでください）： 「① 解说模式 (纯解说/原声混剪) ② 制作路线 (快速/标准)」を同じメッセージで尋ねること。 纯解说 と 原声混剪 は Fast Path 内部のモード（target_mode 1 と 2）です。Standard Path にはありません。パスを選ぶ際にこれらも同時に尋ねると、選択の順序を誤らせ、選択ツリーの異なる階層を混同させてしまいます。

2つのワークフローパス

ナレーション付きの完成動画は、2つのエンドツーエンドのパスで作成できます。開始前にユーザーにどちらを選ぶか確認してください。

	高速パス（原创文案、おすすめ）	標準パス（二创文案）
パイプライン	material → fast-writing → fast-clip-data → video-composing → magic-video*	material → popular-learning** → generate-writing → clip-data → video-composing → magic-video*
コスト／速度	より高速で低コスト	ナレーションの品質がより高い
使用する場面	ユーザーがスタイルを参考にしたナレーションを希望しない限り、デフォルトで使用	ユーザーが参考スタイルを学習したナレーションを希望する場合

* magic-video は任意です。ユーザーが明示的に希望した場合のみ使用します。 ** 既成のテンプレートを使用する場合、popular-learning は省略できます（推奨）。

⚠️ パスの選択は単独で行う決定事項です — 「高速と標準のどちらにしますか？」と、専用のメッセージでユーザーに尋ねてください。自動で選択しないでください。target_mode やその他の追加質問とまとめないでください。

⚠️ パスの選択は動画ごとに、その都度判断します。 同じセッション内の前の動画でパスを切り替えていた場合（たとえば、失敗を受けて高速から標準に切り替えた場合）でも、その選択は今回の動画には影響しません。新しい動画ごとに必ず改めてパスを尋ねてください。前回のセッションの選択を引き継いだり、推測したりしないでください。

高速パスの内部設定：target_mode（パスが高速だと確定した後にのみ質問）

ユーザーが標準パスを選んだ場合、このセクション全体をスキップしてください。target_mode は fast-writing の内部にのみ存在します。

モード	使用する場面	必須入力
"1" 热门影视 (纯解说)	既知の映画。あらすじのみをもとにナレーションを作成	confirmed_movie_json；episodes_data は不要
"2" 原声混剪 (Original Mix)	既知の映画で、SRT がある場合	confirmed_movie_json + episodes_data[{srt_oss_key, num}]
"3" 冷门/新剧 (New Drama)	知名度の低い／新しいコンテンツ	episodes_data[{srt_oss_key, num}]；confirmed_movie_json は任意

リソース選択プロトコル

タスクを開始する前に、以下の順序で、各ステップでユーザーに明示的に確認しながらリソースを収集してください。

1. ソースファイル（動画 + SRT）— material list または file upload から
2. BGM — bgm list から
3. 吹き替え音声 — dubbing list から
4. ナレーションスタイルのテンプレート — task narration-styles から

一覧表示コマンド、応答形式、フィールドのマッピングについては、references/resources.md を参照してください。

⚠️ すべてのリソース選択ステップに適用される共通ルール：

1. コンテキストで事前に絞り込む。 対応している場合は、リソースごとのフィルターフラグを使用してください。例：bgm list --search、dubbing list --lang、task narration-styles --genre。material list はこれらのフラグを受け付けません — JSON をページネーションし、grep -i／python3 -c でプログラムから検索してください。
2. デフォルトの提示数は5～8件とし、リソース ID と主要な説明フィールドを含めてください。
3. ユーザーに希望がない場合：おすすめを3件、それぞれ1行の理由とともに提示してください。それでも確認を待ってください。
4. リソースは1つずつ確認する。 現在のリソースが確定するまで、次へ進まないでください。

⚠️ 吹き替えと文章生成の language の不一致を確認する：ユーザーが事前に指定した language の値と選択した音声が一致しない場合、不一致を伝え、続行する前に確認してください。（一般的な言語チェーンのルールは上記の Agent Rules に記載されています。）

高速フロー — 概要

詳細なパラメーター表、target_mode のすべてのケース、完全な JSON の例については、references/workflows.md を参照してください。

ステップ 0 — 素材を探し、target_mode を決定する：

1. 素材を一覧表示します：narrator-ai-cli material list --json --page 1 --size 100。JSON 出力を対象に grep -i または python3 -c でプログラムから検索します。切り詰められている可能性があるため、ターミナルの表示だけに頼らないでください。total > 100 の場合は、すべて取得できるまでページネーションします（--page 2 など）。
2. 素材内に見つかった場合 → ユーザーに、ナレーションのみ（target_mode=1）とオリジナル映像のミックス（target_mode=2）のどちらにするか尋ねます。素材のフィールドから confirmed_movie_json を作成します（マッピングは references/resources.md を参照）。
3. 見つからず、タイトルが分かっている場合 → task search-movie "<name>" --json → target_mode=1（ユーザーが SRT をアップロードした場合は target_mode=2）。処理には 60 秒以上かかることがあります（Gradio バックエンド、結果は 24 時間キャッシュされます）。
4. マイナーな作品／新しいコンテンツ → ユーザーがアップロードした SRT を使い、target_mode=3 にします。confirmed_movie_json は省略可能です。

ステップ 1 — fast-writing：learning_model_id、target_mode、playlet_name、confirmed_movie_json および／または episodes_data、model を渡します（料金：纯解说文案 の場合、flash は 1,000 文字あたり 5pts、pro は 1,000 文字あたり 15pts；原片混剪解说文案 の場合、flash は 1,000 文字あたり 12pts、pro は 1,000 文字あたり 40pts）。作成レスポンスから task_id を保存し、トップレベルの .status=2 になるまでポーリングして、完了したタスクの .files[0].file_id を保存します。

ステップ 2 — fast-clip-data：ステップ 1 の task_id と file_id に加え、bgm、dubbing、dubbing_type、および video_oss_key／srt_oss_key／negative_oss_key を含む episodes_data を渡します。トップレベルの .status=2 になるまでポーリングし、レスポンスのトップレベルにある .task_order_num を読み取ります。

ステップ 3 — video-composing：order_num: <ステップ 2 の .task_order_num> のみを渡します。ポーリングすると、.results.tasks[0].video_url に完成した MP4 が格納されています。

ステップ 4（任意）— magic-video：ユーザーから明示的にリクエストされた場合にのみ実行します。references/magic-video.md を参照してください。

標準パス — 概要フロー

詳細なパラメータ表と JSON の例は references/workflows.md にあります。

ステップ 0 — 素材：Fast Path と同じ素材／アップロードフローを使用します。episodes_data では、video_file_id を video_oss_key と negative_oss_key に、srt_file_id を srt_oss_key に使用します。

ステップ 1 — popular-learning（事前構築済みテンプレートを使用する場合はスキップ）：video_srt_path、narrator_type、model_version を渡します。トップレベルの .status=2 になるまでポーリングし、.results.tasks[0].task_result の JSON を解析します。agent_unique_code が learning_model_id です。または、task narration-styles --json の事前構築済みテンプレートの id をそのまま使用します。

ステップ 2 — generate-writing：learning_model_id、playlet_name、playlet_num、episodes_data に加えて、必須の追加フィールドを 3 つ渡します。target_platform（例："douyin"）、vendor_requirements（該当しない場合は ""）、target_character_name（該当しない場合は ""）です。いずれかを省略すると、10001 ... Field required が返されます。すべてのパラメータ表は references/workflows.md を参照してください。作成レスポンスの task_id を保存します。

ステップ 3 — clip-data：order_num（ステップ 2 でポーリングしたタスクレコードのトップレベルの .task_order_num。例：generate_writing_xxxxx）、および bgm、dubbing、dubbing_type を渡します。⚠️ Fast Path の fast-clip-data とは異なり、こちらの clip-data が受け取るのは task_id ではなく order_num です。トップレベルの .status=2 になるまでポーリングします（ステップ 4 の必須前提条件です）。ただし、video-composing には clip-data 自身の task_order_num を使用しないでください。ステップ 4 で使用するのは generate-writing のものです。

ステップ 4 — video-composing：order_num + bgm + dubbing + dubbing_type を渡します（4 つすべて必須です。ステップ 3 の BGM／音声の値を再度渡してください。API はこれらを引き継がないため、order_num のみを送信すると 10001 查询解说工程任务结果失败 が返されます）。⚠️ Standard Path では generate-writing の task_order_num（generate_writing_xxxxx）を使用し、clip-data のものは使用しません。clip-data は前提条件として、先にトップレベルの .status=2 に到達している必要がありますが、clip-data 自身の task_order_num（generate_clip_data_xxxxx）を送信すると 10001 任务关联记录信息缺失 が返されます。これは Fast Path（fast-clip-data が正しい基準となる）とは逆です。Important Notes #4 を参照してください。ポーリング後、.results.tasks[0].video_url が完成した MP4 です。

ステップ 5（任意）— magic-video：ユーザーから明示的なリクエストがあった場合のみ実行します。references/magic-video.md を参照してください。

単独タスク

# Voice clone — input audio_file_id, returns voice_id
narrator-ai-cli task create voice-clone --json -d '{"audio_file_id": "<file_id>"}'

# Text to speech — input voice_id + audio_text
narrator-ai-cli task create tts --json -d '{"voice_id": "<voice_id>", "audio_text": "Text to speak"}'

どちらも任意の clone_model を受け付けます（デフォルト：pro）。

重要な注意事項

1. target_mode=1 と 2 では confirmed_movie_json が必須で、3 では任意です。事前構築済み素材から見つかった場合は素材フィールドから作成し、それ以外の場合は search-movie を使用します。
2. file_id は必ず file list または material list から取得してください。 推測してはいけません。
3. search-movie には 60 秒以上かかる場合があります（Gradio バックエンドで、結果は 24 時間キャッシュされます）。
4. video-composing.order_num はパスによって異なります。使用する上流タスクの task_order_num はパスごとに異なります（フィールド名のルール、つまり 16 進数の order_num ではなく task_order_num を使用するルールは、上記の Agent Rules に記載されています）。
   • Fast Path → fast-clip-data の task_order_num を使用します（形式：fast_writing_clip_data_xxxxx）。
   • Standard Path → generate-writing の task_order_num を使用します（形式：generate_writing_xxxxx）。clip-data ステップ自身の task_order_num（generate_clip_data_xxxxx）を使用すると 10001 任务关联记录信息缺失 が返されます。clip-data は前提条件として先に完了する必要がありますが、video-composing が参照するのは clip-data の順序ではありません。
5. popular-learning より事前構築済みテンプレートを優先してください。 task narration-styles --json で一覧表示し、上記のリソース URL でプレビューできます。
6. リクエストボディが大きい場合は -d @file.json を使用し、シェルの引用符の問題を避けてください。
7. 高コストのタスクを実行する前に task verify を使用して素材の欠落や無効な素材を早期に検出し、task budget でポイントコストを見積もってください。

データとプライバシー

• API エンドポイント：すべてのリクエストは https://openapi.jieshuo.cn に送信されます。サードパーティのサービスは利用しません。
• ファイルのアップロード：署名付き URL → OSS PUT → コールバック。ファイルは公開されず、アカウントに紐付けられます。
• 認証情報：NARRATOR_APP_KEY は ~/.narrator-ai/config.yaml に保存されます。非公開にし、コミットしないでください。
• 範囲：このスキルは CLI の調整のみを行います。入力として明示的に渡されたもの以外のファイルにはアクセスしません。