Wave Developer API
スコープ付きトークンを作成して、独自のコードからWaveのセッション、文字起こし、アクションアイテムを読み書き・インポートできます。検索、一括エクスポート、Webhookにも対応。
最終更新日:
Wave AI Developer APIは、あなた自身の録音データに対するREST APIです。https://api.wave.co/v1 に対して、Waveで作成したトークンを使ってコードからアクセスすれば、セッション一覧の取得、要約や文字起こしの閲覧、意味による検索、音声のダウンロード、録音のインポート、タイトル・要約・アクションアイテムの更新ができ、さらに録音の処理が完了した瞬間にWebhookで通知を受け取ることもできます。
どのWaveプランでも無料で使え、アクセスできるのは常にあなた自身のアカウントだけです。
トークンを作成する
Wave webアプリ(app.wave.co)で Settings → Developers(「設定」→「開発者」)に進み、API tokens and webhooks(「APIトークンとWebhook」)を開きます。または直接 app.wave.co/settings/integrations/api にアクセスしてもかまいません。
API tokens(「APIトークン」)の下にある Create token(「トークンを作成」)をクリックします。
後で見分けられるように Token name(「トークン名」)を入力し、必要な Permissions(「権限」)にチェックを入れて、Create token をクリックします。1つの連携につき1つのトークンを使う方が、1つの共有トークンを使い回すよりもずっと管理しやすくなります。
Token created(「トークンが作成されました」)ダイアログからトークンをコピーします。Waveはこれを一度しか表示しません:Copy this token now. You will not be able to see it again.(「今すぐこのトークンをコピーしてください。二度と表示されません。」)
すべてのリクエストでベアラートークンとして送信します:
curl -H "Authorization: Bearer wave_api_xxx..." \
https://api.wave.co/v1/sessionsトークン一覧には、各トークンの名前、wave_api_ プレフィックス、権限、作成日時・最終使用日時・有効期限が表示されます。ゴミ箱アイコンをクリックすると Revoke this token?(「このトークンを取り消しますか?」)と確認され、Revoke token(「トークンを取り消す」)を選ぶと即座に無効化され、そのトークンを使っているものはすべて401エラーを受け取るようになります。
APIトークンは作成から1年で有効期限が切れます。数か月問題なく動いていた連携が突然401 invalid_token を返すようになったら、トークン一覧の Expires(「有効期限」)日付を確認し、新しいトークンを作成してください。
権限
権限はトークンごとに設定します。必要最小限の権限だけを付与してください。
| 権限 | 許可される操作 |
|---|---|
| Read sessions | セッションの一覧表示・閲覧、統計情報、people、一括エクスポート |
| Write sessions and action items | タイトル、メモ、要約、タグ、お気に入り、アクションアイテムの更新 |
| Delete sessions | セッションの完全削除 |
| Search sessions | ライブラリ全体に対するセマンティック検索 |
| Read transcripts | 話者セグメント付きの完全な文字起こし |
| Access media | 音声・動画の署名付きダウンロードURL |
| Read account | アカウント情報とサブスクリプションの状態 |
| Manage webhooks | Webhookエンドポイントの登録と管理 |
| Read event feed | イベントフィードの取得と確認応答 |
| Read folders | フォルダの一覧表示・閲覧(Read sessions でも可能) |
| Manage folders | フォルダの作成、名前変更、色変更、ピン留め、並べ替え、削除、セッションの追加・削除 |
| Share sessions and manage access | 自分のセッションを他のWaveユーザーと共有し、アクセス権を持つ人を確認し、削除する |
| Import recordings (uses your import allowance) | リンクまたはアップロードで音声・動画をWaveにインポートする。write権限には含まれないため、個別にチェックが必要 |
対応する権限なしでエンドポイントを呼び出すと、不足している権限名を含む403エラーが返されます。
データを読み取る
GET /v1/sessions— 新しい順、カーソルによるページネーション、type・since・folder・tag・personでフィルタ可能。処理が完了したセッションのみ返されます。folderには ID、名前、またはParent/Child形式のパスを指定できます。親フォルダを指定するとサブフォルダ内のセッションも含まれます(include_subfolders=falseを渡すと除外)。GET /v1/sessions/:id— タイトル、長さ、Markdown形式の要約、メモ、タグ、お気に入り。電話の場合は通話方向と電話番号も含まれます。GET /v1/sessions/:id/transcript— フラットな文字起こし文字列と、タイムスタンプ・話者ラベル付きセグメント。GET /v1/sessions/:id/action-items— 構造化されたアクションアイテムとバージョン番号。GET /v1/sessions/:id/media— 1時間有効な音声・動画の署名付きURL。POST /v1/sessions/search— セマンティック検索、最大50件、任意でタグによる絞り込み可能。POST /v1/sessions/bulk— 1回の呼び出しで最大50セッションを、要約・文字起こし付きで取得。バックフィルに最適な方法です。GET /v1/folders、GET /v1/folders/:id、GET /v1/sessions/stats— フォルダ情報、タイプ・プラットフォーム別の集計。 フォルダは1階層までネストできます。各フォルダにはparent_idがあり(最上位はnull)、GET /v1/folders?parent_id=noneまたは?parent_id={id}で1階層分を一覧できます。
People
PeopleはVoice ID(Voice ID)として保存した声の主のことです。必要なのは Read Sessions 権限のみで、読み取り専用です。
GET /v1/people— 声を保存した全員の情報。各人物が何件の録音に登場するか、最後に検出された日時を含みます。自分自身の声にはis_meマークが付き、先頭に表示されます。GET /v1/people/:id/sessions— 特定の人物が登場する録音を新しい順に取得、カーソルによるページネーション、type・from・toでフィルタ可能。各行には、その人がどれくらい発言したか、その文字起こしでの名前、最も長い発言3件が表示されます。自分自身の声については、idとしてmeを使います。GET /v1/sessions?person=:id— 通常のセッション一覧を、その人物が登場する録音に絞り込んだもの。
音声サンプルが返されることはなく、完全な文字起こしも返されません。3行以上が必要な場合は、文字起こしを別途取得してください。Waveで2つのVoice IDを統合した場合、古いidは404を返し、その merged_into に使うべきidが示されます。アカウントのpeopleをWaveがまだインデックス中の場合、件数は最新1,000件の録音のみを対象とし、レスポンスには partial: true が付きます。
データを書き込む
PATCH /v1/sessions/:id でタイトル、メモ、要約(Markdown)、タグ、お気に入り、アクションアイテムを設定できます。アクションアイテムについては、まず読み取ってから取得したバージョンを送り返してください。そうすることで、Waveアプリ側での同時編集はサイレントに上書きされるのではなく、拒否されるようになります。POST /v1/folders、PATCH /v1/folders/:id、DELETE /v1/folders/:id、そしてフォルダへのセッション所属を管理するエンドポイント(POST および DELETE /v1/sessions/:id/folders/:folderId)でセッションを整理できます。フォルダは排他的ではないため、1つのセッションが複数のフォルダに入ることができ、フォルダを削除してもその中のセッションは削除されません。 POST /v1/folders に parent_id を渡すとサブフォルダを作成でき、PATCH /v1/folders/:id に渡すとフォルダを移動できます(null で最上位に戻ります)。親は最上位のフォルダである必要があり、サブフォルダを持つフォルダは別のフォルダの中に移動できません。どちらの場合も 400 invalid_parent が返ります。親フォルダを削除すると、そのサブフォルダは最上位に移動します。
DELETE /v1/sessions/:id は完全な削除で、アプリ内での削除とは異なります。復元不可能な操作として扱ってください。
録音のインポート
POST /v1/sessions/import は、音声または動画ファイルからセッションを作成します。Waveはアプリでインポートした場合とまったく同じように文字起こし・要約を行います。このエンドポイントには Import recordings (uses your import allowance) 権限(sessions:import)が必要です。次のいずれかを送信してください:
source_url:ファイル自体への公開httpsリンク。Waveがそれをダウンロードし(最大2GiBまで)、202とstatus: "fetching"を返します。upload:content_type(任意でfilenameとsize_bytes)を指定。Waveは201を返し、署名付きのupload.urlを渡します。15分以内に、与えられたupload.headersをそのまま使ってそのURLにPUTでファイルをアップロードしてください(最大5GiBまで)。アップロードが完了すると、処理は自動的に開始されます。
title、notes、tags、language、recorded_at も渡せます。その後は GET /v1/sessions/:id で processing_status をポーリングするか、Session completed Webhookを待ってください。
curl -X POST https://api.wave.co/v1/sessions/import \
-H "Authorization: Bearer wave_api_xxx..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: standup-2026-10-21" \
-d '{"source_url": "https://example.com/standup.mp3", "title": "Daily standup"}'Idempotency-Key ヘッダーを送ることで、リトライを安全に行えます。同じキーと本文を繰り返すと、2回目のインポートではなく最初に作成したセッションが返されます。
対応フォーマット:MP3、M4A、WAV、AAC、FLAC、OGG、OPUS、WebM、MP4、MOV、AIFF、AMR、WMA、3GP、CAF、MPEG、MPEG-TS。インポートはWaveアプリと同じインポート上限を共有します:1時間あたり12件、1日あたり20件(有料プランの場合は40件・100件、アカウント作成から2日未満の場合はそれより少なくなります)。この上限を超えると429 import_rate_limited が返され、無料プランで残り時間がない場合は403 subscription_required が返されます。
共有
トークンはあなた自身として振る舞うため、他のWaveユーザーがあなたと共有したセッションも、上記の権限の範囲内で読み取れます。GET /v1/shared-sessions でそれらの一覧を取得でき、GET /v1/shared-sessions/{owner_id}/{id} とその /transcript、/action-items、/media で個別に読み取れます。GET /v1/sessions に include=shared を付けると、共有セッションも自分のセッション一覧に混ぜて表示できます。その場合、各行には access(owner または shared)と、共有セッションの場合は所有者の情報が含まれます。共有された行はフォルダやタグでのフィルタができず、共有セッションは読み取り専用で、検索の対象も自分自身のセッションのみです。
Share sessions and manage access 権限があれば、トークンは自分のセッションを共有できます。/v1/sessions/{id}/sharing でアクセス権を持つ人を確認でき、その配下のルートで招待リンクの作成、メールでの招待(1回の呼び出しで最大10アドレス)、保留中の招待のキャンセル、特定の人の削除、リンクのリセットが行えます。全エンドポイント一覧と制限についてはClaude、ChatGPT、API、CLIからのセッション共有を参照してください。
レート制限
各トークンには1分あたり60リクエスト、1日あたり10,000リクエストの上限が設定されています。レスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれ、429エラーには Retry-After が含まれます。すぐにリトライせず、少し待ってから再試行してください。
同じ検索クエリを1時間に10回以上繰り返すと、やはり429が返されます。同一の検索は同一の結果を返すため、新しいものを見つけるにはWebhookや GET /v1/sessions?since= を使ってください。
Webhook
ポーリングする代わりに、Waveからあなたへ向けてPOSTしてもらうこともできます。Webhooks セクションで Add webhook(「Webhookを追加」)をクリックし、Endpoint URL(「エンドポイントURL」、HTTPSのみ対応。プライベートアドレスに解決されるURLは拒否されます)を入力、Events(「イベント」)を選択して、Create webhook(「Webhookを作成」)をクリックします。Signing secret(「署名シークレット」)は一度しか表示されないので、その場で保存してください。Webhookは最大5つまで作成できます。
イベントの種類:Session completed(処理が完了し、要約が取得可能になった後に一度だけ送信される、多くの連携が必要とするイベント)、Session updated、Action items updated(API経由でアクションアイテムが書き込まれたり編集されたりしたときに送信される)、Session deleted。自分のコードから POST /v1/webhooks(または wave webhooks create)でWebhookを登録することもできます。
Session completed は、要約以上の情報を含むこともできます。POST /v1/webhooks でWebhookを作成する際、または PATCH /v1/webhooks/:id で変更する際に、include オブジェクトを渡してください:
{ "include": { "summary": true, "transcript": true, "action_items": true } }summary はデフォルトで有効、transcript と action_items はデフォルトで無効です。文字起こしを含めるには、Read transcripts 権限を持つトークンが必要です。非常に長い文字起こしは200,000文字で切り詰められ、transcript_truncated: true が付きます。残りは GET /v1/sessions/:id/transcript から取得してください。アクションアイテムは、セッション完了時点のものが含まれます。Waveが後からさらに追加した場合は、Action items updated イベントが届きます。それ以外のイベントは常に通常のセッション情報のみを含みます。
各配信はあなたのシークレットで署名され、X-Wave-Webhook-Id、X-Wave-Webhook-Timestamp、X-Wave-Webhook-Signature ヘッダーとともに届きます。ペイロードを信頼する前に署名を検証してください。署名対象となる正確な文字列はAPIリファレンスに記載されています。
Waveは1イベントにつき1回の配信を保証しているわけではありません。タイムアウト(10秒)したり、2xx以外のステータスが返された配信は、短い間隔(約10秒後、1分後、5分後)で最大3回まで再試行され、同じイベントが複数回届くことも正常な挙動としてあり得ます。ハンドラーは冪等になるよう作ってください:X-Wave-Webhook-Id をキーとして使い、すでに処理済みのidは無視し、すばやく2xxを返すようにします。この再試行期間よりも長くエンドポイントがダウンしていた場合、取りこぼしたイベントは失われるため、その場合は下記のイベントフィードを使って取り戻してください。
エンドポイントが10回連続で失敗すると、Waveはそれを Turned off automatically(「自動的にオフになりました」)とマークし、送信を停止します。エンドポイントを修正した後、該当のWebhookの行で Turn webhook back on(「Webhookを再度オンにする」)を選択してください。
サーバーがない場合はイベントフィードを使う
公開URLをホストできない場合は、代わりにポーリングしてください。GET /v1/events は、トークンごとにWaveが管理するカーソル以降のイベントを返し、POST /v1/events/ack は処理済みのイベント分だけカーソルを進めます。そのため、スクリプトを再起動してもすべてが再送されることはありません。ページはデフォルトで50件、最大200件まで取得でき、フィードにはアクションアイテムの変更も含まれます。Read event feed 権限が必要です。
ポーリングのループを自分で書きたくない場合は、Wave CLIの wave events tail がこれをラップしてくれます。
よくある質問
api.wave.co/reference に、すべてのエンドポイント、パラメータ、レスポンス形式がライブサンプル付きで掲載されています。api.wave.co/llms.txt は同じ内容をプレーンテキストにしたもので、これをAIアシスタントに貼り付ければ、連携コードを代わりに書いてもらうこともできます。
常にJSON形式で、code と message を含みます。よくあるものとしては、401 invalid_token(期限切れ、取り消し済み、または入力ミス)、403 insufficient_scope(トークンに必要な権限がない)、429(レート制限)があります。
他の人があなたと共有したものだけです。トークンはそれを作成したアカウントに紐づいており、そのアカウントのセッションと、他のWaveユーザーがそのアカウントと共有したセッション(読み取り専用)を返します。
この記事は役に立ちましたか?
まだお困りですか?