公式APIの無い録音サービスから、別のSaaSへ音声を自動取り込みする指示書

ICレコーダー/録音アプリのクラウド（例: Plaud）にたまる音声を、文字起こし・要約SaaS（例: tl;dv）へ無人で流し込むための指示書。音声の変換もストレージも使わず、中継URLを1枚挟むだけで成立する。

想定読者は AI エージェント。この MD を読ませればそのまま実装できる粒度で書く。

---

0. 結論（先に読む）

• 取り込み先の import API は URL を渡す方式が多い。素直に「元サービスの署名付きダウンロードURL」を渡すと、成功レスポンスが返るのに何も起きないという無言の失敗に高確率で当たる。
• 原因は次の2つで、どちらも中継プロキシ1枚で同時に解決する。
  1. 取り込み先は取得前に HEAD を打つが、S3 等の署名付きURLは署名がメソッド単位なので HEAD に 403 を返す（GET は 200/206 で成功する）。
  2. 取り込み先の URL 長制限（実測で 約2000文字）。署名付きURLは 1500文字級あり、トークンに埋め込むと超える。
• jobId が返っても取り込めたとは限らない。必ず取り込み先の一覧を read-back して実体を確認する。

---

1. 全体構成

元サービスのクラウド ──(署名付きURL)──> 中継プロキシ ──> 取り込み先SaaS
        ▲                                                  │
        └────────── 定期実行するCLI（状態管理・冪等） ◀──────┘

• CLI（PC の定期実行）: 新着録音を検知 → 中継URLを組み立て → 取り込み先の import API を叩く → 取り込み済みを記録
• 中継プロキシ（サーバーレス1関数）: HEAD/GET の両方に正しく応答し、実体は元サービスから都度読んで流すだけ。音声は保存しない

---

2. 元サービスの認証（公式APIが無い場合の典型）

ブラウザのセッションを借りる形になる。多くのサービスが次の3段構成を取る。

種別	寿命の例	用途
ユーザートークン (UT)	1日	ワークスペース一覧の取得、WT の発行
更新トークン (URT)	30日前後	UT の更新
ワークスペーストークン (WT)	数時間	ファイル一覧・ダウンロードURL取得の実 bearer

落とし穴

• 更新トークンの Cookie は Path=/auth/refresh... のようにパス限定で発行されることがある。この場合ブラウザの Cookie 一覧に出てこないので「無い」と誤判定しやすい。
• 更新APIの応答は Set-Cookie ではなく body に入ることがある（access_token / refresh_token）。Set-Cookie だけを見る実装は、更新期限が来た瞬間に必ず壊れる。両方から拾うこと。
• 更新してもトークンの有効期限が延びないサービスがある（セッション単位で固定寿命）。この場合は定期的に人手での取り直しが要る。→ §6 の通知を必ず作る。
• WT は有効期限前でも無効化される（別クライアントが発行し直すと失効する）。exp だけを見ず、失効を表すエラーを検出したら発行し直して1回だけ再試行する。
• リージョンごとに API ホストが分かれる場合がある。トークン(JWT)の region クレームが最も確実な接続先の判定材料。ホストの許可リストは「既知の一覧」に加えて「そのサービスのドメイン配下なら受け入れる」ようにしておくと、増設に追従できる。

更新トークンの取り出し方（人手が1回だけ要る場合）

HttpOnly Cookie はスクリプトから読めない。ブラウザの Console でそのサービス自身の更新APIを呼ぶと、応答 body に両方のトークンが返る。

fetch('<API_BASE>/auth/refresh-user-token', {
  method: 'POST', credentials: 'include',
  headers: { 'content-type': 'application/json' }, body: '{}'
}).then(r => r.json()).then(j => console.log('COPY:' + JSON.stringify({ a: j.access_token, r: j.refresh_token })))

Chrome は初回の貼り付けを拒否するので、Console に allow pasting と手入力させる手順を必ず案内に含める。

---

3. 中継プロキシ（サーバーレス1関数・依存ゼロ）

URL の形

https://<host>/a/<token>/audio.<ext>

• トークンとファイル名は別のパスセグメントにする。トークンは . を含むので、/a/<token>.<ext> のような1セグメント形式にするとルーティングが誤爆する。
• <ext> は Content-Type の決定に使う。

トークンの中身

署名付きURLを埋め込まない（URL長制限に当たる）。代わりに「ダウンロードURLを取り直すのに必要な最小限」を入れ、AES-256-GCM で暗号化する。

token = base64url( iv(12B) ‖ authTag(16B) ‖ ciphertext )
平文  = {"b": <APIベースURL>, "w": <ワークスペーストークン>, "f": <ファイルID>, "x": <失効UNIX秒>}
鍵    = sha256(PROXY_SECRET)

• 暗号化は必須。ワークスペーストークンは元サービスへの実アクセス権なので、平文で URL に載せると取り込み先のログに残った時点で漏洩する。
• 復号失敗 → 403 / 失効 → 410 / ベースURLがサービスのドメイン外 → 400。

応答

• HEAD: 上流へ Range: bytes=0-0 の GET を打ち、Content-Range から総サイズを得て、200 + Content-Type + Content-Length + Accept-Ranges: bytes を本文なしで返す。これが無いと取り込みが無言で失敗する。
• GET: 上流へ GET（Range があれば転送）。ステータス(200/206)・Content-Length・Content-Range・Accept-Ranges を引き継ぎ、本文をストリームで流す。
• それ以外のメソッド → 405。Cache-Control: private, no-store を付ける。
• 取得したダウンロードURLのホストを許可リストで検査する（オープンプロキシ化の防止）。リダイレクト追従による回避も塞ぐ。
• 秘匿値（シークレット・トークン・上流URL）をログにも応答本文にも出さない。

---

4. 取り込み側 CLI

判定と絞り込み

• ゴミ箱・取り込み済み・短すぎるもの（例: 5分未満）を除外
• 長さ上限を確認する（例: 3時間超は受け付けない取り込み先がある）。超過分は別途分割が要るので、黙って落とさずログに出す
• 初回実行では過去分を一括投入しない。既存を「確認済み」として記録するだけにし、--backfill で明示された時だけ遡る。履歴が数百件ある環境で事故になる

時刻・長さの単位

秒とミリ秒が混在しがち。start_time / end_time があるならその差分と突き合わせて単位を実測で決める。閾値だけで判定すると短い録音を取り違える。

冪等性と状態

• 取り込み済みIDを状態ファイルに保存し、書き込みは一時ファイル→rename の atomic write
• Windows では上書き rename が EPERM で弾かれることがある（ウイルス対策やインデクサが一瞬ハンドルを掴む）。取りこぼすと「取り込み済み」の記録が消えて二重投入になるので、短い再試行 → コピーへのフォールバックまで用意する

表示名

一覧APIの「ファイル名」フィールドが**ストレージ上のキー（ハッシュ.拡張子）**であることがある。人が付けた題名は別フィールドなので取り違えないこと。取り違えると取り込み先に意味不明な名前の会議が並ぶ。

---

5. 検証（ここを省くと必ず嘘の完了報告になる）

1. 中継URL単体で HEAD が 200 + 正しい Content-Length、GET が 206 を返すことを確認
2. 取り込み先の一覧を read-back し、件数の増加と実体（名前・長さ）を確認
3. 可能なら文字起こしの中身まで確認する
4. 切り分けが必要な時は「失効しない公開ファイルURL」を1件流す対照実験を打つ。これが通って自前URLが通らなければ、原因は URL 側にあると確定できる
5. 対応形式はドキュメントより実測を優先する。ドキュメントの対応一覧に無い形式が実際には通ることがある（逆もある）

---

6. 非同期処理には必ず「戻り導線」を作る

定期実行の標準出力は誰も読まない。期限切れで止まっても誰も気付かないのが最悪のケース。

• 残り日数がしきい値を切ったら/失敗したら、復旧手順ごと（URL・貼り付ける1行・完了の見え方）を通知する
• 通知先は「その人が毎日必ず見る場所」かつ「実際に復旧作業をする場所」。エージェント経由で作業しているなら、エージェントのセッション開始時に提示させるのが最短
• 同じ用件は24時間に1回だけ送る（定期実行のたびに鳴らさない）
• 健全に戻ったら通知を自分で消す
• webhook は使う前に生存確認する。失効した webhook に投げ続けて「通知しているつもり」になっている事故は珍しくない

---

7. Windows で定期実行する場合の注意

• 登録スクリプト（.ps1）に日本語を書くなら BOM 付き UTF-8 で保存する。BOM 無しだと Windows PowerShell 5.1 が Shift-JIS と誤読し、コメント1行で構文エラーになる。本文を ASCII のみにするのが確実
• PC が停止していた時に追いかけ実行するオプションを付ける
• 実行間隔は後から変えられる形にしておく（要望は必ず変わる。「15分ごと」「毎晩1回」「1時間ごと」と揺れた実例あり）

---

8. この構成でやらないこと

• 音声の変換（多くの場合そもそも不要。まず実測で確かめる）
• 音声をクラウドに保存すること（中継は都度読んで流すだけにする）
• 取り込み先の資格情報を中継側に置くこと（暗号化して URL に載せる方が運用が楽）