0. ファーストコンタクト
ユーザーがこのスキルを開くか、最初のメッセージを送信した場合、すぐに挨拶してください:
ようこそ!自動字幕生成オンライン機能を使用して、動画の正確な字幕を自動生成します。動画ファイルやリンクを教えてください。希望の言語や字幕スタイルをお知らせいただければ、数分で字幕付き動画またはSRTファイルをご用意します。最初の動画の字幕を作成しましょうか?
試してみてください:
- 「このMP4インタビューに英語の字幕を生成し、YouTubeにアップロードできるSRTファイルを出力してください。」
- 「MOVチュートリアル動画に、白の太字テキストと半透明の黒背景で字幕を焼き付けてください。」
- 「スペイン語のウェビナー(WebM形式)を文字起こしし、スペイン語と英語のバイリンガル字幕を作成してください。」
重要: 初回コンタクトでは常に積極的に挨拶してください。接続中に設定を行っていることをユーザーに伝えてください。初回コンタクトでは常に積極的に挨拶してください。
自動セットアップ
ユーザーが初めて操作する際、接続をセットアップします:
- トークンの確認:
NEMO_TOKEN環境変数が設定されていればそれを使用します。そうでなければ: - クライアントIDの読み取りまたは生成:
~/.config/nemovideo/client_idが存在すれば読み取ります。- 存在しなければUUIDを生成し、
~/.config/nemovideo/client_idに保存します。
- 匿名トークンの取得:
返ってきたcurl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"tokenをこのセッションでNEMO_TOKENとして保存します。100クレジットの無料枠が提供されます。 - セッションの作成(§3.0): すぐに作業できるようにします。
ユーザーに簡単に「設定中…準備完了!」と伝え、リクエストの処理を進めます。
すべての話し言葉を瞬時に画面上のテキストに
自動字幕生成オンラインスキルは、動画制作で最も時間がかかる作業の1つである、正確でタイミングの合ったキャプションを、字幕エディターで何時間も作業することなく実現するために存在します。YouTubeチュートリアル、企業研修モジュール、ソーシャルメディアリールなど、読みやすい字幕は視聴時間とアクセシビリティコンプライアンスを劇的に向上させます。
このスキルは会話型編集モデルで動作します。つまり、フォームに入力したりタイムラインを操作したりする必要はありません。代わりに、必要なもの(言語、キャプションの配置、スタイル設定、キャプションを動画に焼き付けるか別のSRTファイルとして出力するかなど)を説明するだけで、あとはスキルが処理します。結果を調整したい場合は、同僚にメッセージを送るように、調整内容を伝えるだけで結果を調整できます。
舞台裏では、OpenClawエージェントがパイプラインを調整し、動画の音声を高精度な音声認識エンジンに送信し、文字起こしセグメントを正確なタイムスタンプに合わせ、フォーマットルールを適用し、選択した形式で出力をパッケージ化します。エージェントは、重なり合う音声、背景ノイズ、高速な会話などのエッジケースも処理し、キャプションが読みやすく同期された状態を維持します。
環境変数
| 変数 | 必須 | デフォルト値 |
|---|---|---|
NEMO_TOKEN | いいえ | 自動生成(100クレジット無料、7日間有効、設定→APIトークンから取り消し可能) |
NEMO_API_URL | いいえ | https://mega-api-prod.nemovideo.ai |
NEMO_WEB_URL | いいえ | https://nemovideo.com |
NEMO_CLIENT_ID | いいえ | 自動生成されたUUID、~/.config/nemovideo/client_idに保存(UUIDのみ、機密情報は含まれません) |
SKILL_SOURCE | いいえ | インストールパスから自動検出、フォールバックはunknown |
NEMO_TOKENが設定されていない場合は、トークンを取得します(X-Client-Idヘッダーが必要です):
# 永続化されたクライアントIDを生成または読み取り
CLIENT_ID="${NEMO_CLIENT_ID:-$(cat ~/.config/nemovideo/client_id 2>/dev/null)}"
if [ -z "$CLIENT_ID" ]; then
CLIENT_ID=$(uuidgen 2>/dev/null || echo "client-$(date +%s)-$RANDOM")
mkdir -p ~/.config/nemovideo && echo "$CLIENT_ID" > ~/.config/nemovideo/client_id
fi
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
# → {"code":0,"data":{"token":"nmv_usr_xxx","credits":100,...}}
tokenをNEMO_TOKENとして、CLIENT_IDをNEMO_CLIENT_IDとして保存します。匿名: クライアントごとに7日間で1つのトークン。トークンは7日間有効で、nemovideo.comの設定→APIトークンからいつでも取り消し可能です。トークンの有効期限が切れた場合は、同じX-Client-Idを使用して新しいトークンをリクエストしてください。
ローカル永続化: このスキルは~/.config/nemovideo/client_idに書き込み、セッション間でクライアントIDを永続化します。これにより、リクエストごとに新しいIDが生成されるのを防ぎ、IPごとのレート制限(デフォルトでIPあたり7日間で10トークン)にすぐに達するのを回避します。ファイルにはUUIDのみが含まれ、認証情報はローカルに保存されません。
2. エンドポイントディレクトリとルーティングロジック
すべてのキャプション関連リクエストは特定のルートにマッピングされます。以下の表を参照して、各アクションを正しいエンドポイントとメソッドに一致させてください。
| ユーザーが言ったこと... | アクション | SSEをスキップ? |
|---|---|---|
| "export" / "导出" / "download" / "send me the video" | → §3.5 エクスポート | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 クレジット | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 状態 | ✅ |
| "upload" / "上传" / ユーザーがファイルを送信 | → §3.2 アップロード | ✅ |
| その他(生成、編集、BGM追加など) | → §3.1 SSE | ❌ |
3. 字幕生成の運用フロー
$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai}, $TOKEN = ${NEMO_TOKEN}, $WEB = ${NEMO_WEB_URL:-https://nemovideo.com}.
スキル属性変数 — ハードコードしないこと:
$SKILL_NAME= このファイルのYAMLフロントマターname$SKILL_VERSION= このファイルのYAMLフロントマターversion$SKILL_SOURCE= 実行時に最初に一致するものを検出:- 設定されている場合は環境変数
SKILL_SOURCE - このファイルのパスに既知のプラットフォームディレクトリが含まれている場合(例:
~/.clawhub/→clawhub、~/.cursor/skills/→cursor) - フォールバック:
unknown
- 設定されている場合は環境変数
重要: すべてのAPIリクエスト(レンダリング/エクスポート/アップロード/状態/クレジットを含む)はこれらのヘッダーを含める必要があります。ヘッダーがないと、エクスポートが402で失敗する可能性があります。
X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE
3.0 キャプションセッションの初期化
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" \
-d '{"task_name":"project","language":"<lang>"}'
# → {"code":0,"data":{"task_id":"...","session_id":"..."}}
文字起こしやタイミングデータを交換する前に、セッションを確立する必要があります。このハンドシェイクにより、バックエンドがキャプションジョブを追跡するために使用する永続的なコンテキストが作成されます。これがないと、後続の呼び出しは正しく解決されません。
ブラウザで開く: セッション作成後、ユーザーにNemoVideoでタスクを表示/編集するためのリンクを提供します:
$WEB/workspace/claim?token=$TOKEN&task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 SSEによるストリーミングメッセージ
curl -s -X POST "https://mega-api-prod.nemovideo.ai/run_sse" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "Accept: text/event-stream" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" --max-time 900 \
-d '{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}'
すべてのリアルタイムキャプションイベント(SRTチャンクの配信、タイミング確認、ステータス更新を含む)は、アクティブなセッションに関連付けられたサーバー送信イベントチャネルを介して送信されます。
SSE処理
| イベント | アクション |
|---|---|
| テキスト応答 | GUI翻訳を適用(§4)、ユーザーに提示 |
| ツール呼び出し/結果 | 静かに待機、転送しない |
heartbeat / 空のdata: | 待機を継続。2分ごとに「⏳ まだ処理中です...」 |
| ストリームクローズ | 最終応答を処理 |
一般的な所要時間: テキスト5〜15秒、動画生成100〜300秒、編集10〜30秒。
タイムアウト: ハートビートのみが10分続いた場合 → タイムアウトとみなします。生成中は決して再送信しないでください(重複+二重課金)。
以前の応答が正常だった場合、末尾の「一時的な問題が発生しました」は無視します。
サイレントレスポンスフォールバック(重要)
字幕編集操作の約30%で、応答本文にテキストがゼロで返されます。キャプション行も確認文字列も何もありません。これは予期される動作であり、障害ではありません。発生した場合: まず、リクエストを再試行したり、失敗としてフラグを立てたりしないでください。次に、Query Stateエンドポイントを呼び出して現在のキャプションタイムラインを直接取得します。第三に、そのエンドポイントから返されたSRTデータを信頼できる結果としてユーザーに表示します。第四に、その状態を真実の情報源として会話を通常通り続けます。
2段階生成: 自動字幕パイプラインで処理された生の動画は、自動的に2段階のバックエンドシーケンスをトリガーします。第1段階ではベースのキャプショントラック(動画タイムラインに同期された生の文字起こし)を配信します。第2段階はクライアントからのプロンプトなしで起動します。バックエンドがキャプション出力にBGMと生成されたタイトルカードを追加します。エクスポートの準備が整う前に、両方の段階が完了している必要があります。両方のステージ信号が到着するまで、SSEチャネルをポーリングまたはリッスンします。
3.2 キャプション用メディアファイルのプッシュ
ファイルアップロード: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -F "files=@/path/to/file"
URLアップロード: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"urls":["<url>"],"source_type":"url"}'
パスにmeを使用します。バックエンドがトークンからユーザーを解決します。
サポートされている形式: mp4、mov、avi、webm、mkv、jpg、png、gif、webp、mp3、wav、m4a、aac。
アップロードエンドポイントは、字幕エンジンが文字起こしとキャプション同期を行うビデオおよびオーディオソースファイルを受け入れます。
3.3 利用可能なキャプションクレジットの確認
curl -s "https://mega-api-prod.nemovideo.ai/api/credits/balance/simple" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
# → {"code":0,"data":{"available":XXX,"frozen":XX,"total":XXX}}
長い文字起こしジョブを開始する前に、クレジットエンドポイントにクエリを実行して、操作に十分な残高があることを確認します。
3.4 現在のジョブとキャプション状態の取得
curl -s "https://mega-api-prod.nemovideo.ai/api/state/nemo_agent/me/<sid>/latest" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
ユーザーにはmeを使用します。バックエンドがトークンから解決します。
主要フィールド: data.state.draft、data.state.video_infos、data.state.canvas_config、data.state.generated_media。
ドラフトフィールドマッピング: t=トラック、tt=トラックタイプ(0=ビデオ、1=オーディオ、7=テキスト)、sg=セグメント、d=期間(ミリ秒)、m=メタデータ。
エクスポート可能なドラフト: draft.tが存在し、空でないsgを持つトラックが少なくとも1つある場合。
トラックサマリー形式:
タイムライン(3トラック): 1. ビデオ: 都市のタイムラプス(0-10秒) 2. BGM: Lo-fi(0-10秒、35%) 3. タイトル: 「Urban Dreams」(0-3秒)
3.5 最終キャプションパッケージのエクスポートと配信
エクスポートはクレジットを消費しません。 生成/編集のみがクレジットを消費します。
完成した字幕ファイルのエクスポート(SRT、VTT、または動画に焼き付ける場合)は、クレジットを消費しません。シーケンスは次のように実行されます: (a) 状態クエリを介して両方のパイプラインステージが完了したことを確認します。(b) ペイロードで目的のキャプション形式を指定してエクスポートエンドポイントを呼び出します。(c) 応答で署名付き配信URLを受信します。(d) そのURLからキャプション付きアセットをストリーミングまたはダウンロードします。(e) セッションに配信を確認して、バックエンドがジョブをクローズとしてマークできるようにします。
b) 送信: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}'
注: sessionIdはcamelCaseです(例外)。失敗した場合 → 新しいidを作成し、1回再試行します。
c) ポーリング(30秒ごと、最大10回): curl -s "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda/<id>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
ステータスはトップレベルのstatus: pending → processing → completed / failed。ダウンロードURLはoutput.url。
d) output.urlからダウンロード → ユーザーに送信。フォールバック: https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download。
e) 動画を配信する際は、常にタスク詳細リンクも提供: $WEB/workspace/claim?token=$TOKEN&task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
進行状況メッセージ: 開始「⏳ レンダリング中 約30秒」→「⏳ 50%」→「✅ 動画準備完了!」+ファイル+タスク詳細リンク。
3.6 SSE切断後の再接続
SSE接続は切断されます。そのための計画を立ててください。復旧は5つのステップに従います: 1) タイムアウトを待たずに、クライアント側で切断イベントを即座に検出します。2) 新しいセッションを作成しないでください。既存のセッションIDは引き続き有効です。3) 同じセッションIDと、最後に受信したイベント識別子に設定されたLast-Event-IDヘッダーを使用して、SSEチャネルを再度開きます。4) 現在のキャプション状態をクエリして、ギャップ中に到着したSRTチャンクやタイミングイベントをバックフィルします。5) 切断前に最後に確認されたキャプションタイムスタンプから通常のストリーミングを再開し、切断前の文字起こしから何も破棄しません。