🎙️ AccuNote API ドキュメント

📋 概要

AccuNote は WebSocket ベースのリアルタイム音声認識サービスを提供しています。本ドキュメントでは、API を使用してサービスを利用する方法を説明します。

🔑 認証

すべての API リクエストは、WebSocket 接続確立後に認証メッセージを送信する必要があります：

{
  "type": "connect",
  "token": "your-api-key-here"
}

🌐 WebSocket 接続

接続フロー

1. wss://api.accunote.ai/reco への WebSocket 接続を確立
2. 認証メッセージを送信（API Key を含む）
3. 接続確認メッセージを受信
4. 認識開始メッセージを送信
5. 音声データを送信（Opus エンコード）
6. 認識結果を受信
7. 認識停止メッセージを送信

📨 メッセージフォーマット

1. 認証メッセージ（クライアント → サーバー）

{
  "type": "connect",
  "token": "ak_xxxxxxxxxxxxxxxxxxxx"
}

2. 接続確認（サーバー → クライアント）

{
  "type": "connected",
  "message": "接続成功"
}

3. 認識開始（クライアント → サーバー）

{
  "type": "start",
  "config": {
    "sampleRate": 16000,
    "channels": 1,
    "encoding": "opus",
    "language": "ja-JP"
  }
}

パラメータ	型	説明	指定可能な値
sampleRate	int	サンプリングレート	16000（推奨）
channels	int	チャンネル数	1（モノラル）
encoding	string	音声エンコード	opus
language	string	認識言語	ja-JP, en-US, zh-CN

4. 音声データ（クライアント → サーバー）

バイナリデータを送信（Opus エンコードされた音声ストリーム）

5. 認識結果（サーバー → クライアント）

{
  "type": "recognition",
  "result": {
    "text": "認識されたテキスト内容",
    "isFinal": false,
    "confidence": 0.95,
    "timestamp": 1234567890
  }
}

フィールド	型	説明
text	string	認識されたテキスト
isFinal	boolean	最終結果かどうか
confidence	float	信頼度（0-1）
timestamp	int	タイムスタンプ（ミリ秒）

6. 認識停止（クライアント → サーバー）

{
  "type": "stop"
}

7. ハートビートメッセージ（双方向）

// クライアント送信
{
  "type": "ping",
  "timestamp": 1234567890
}

// サーバー応答
{
  "type": "pong",
  "timestamp": 1234567890
}

💻 コード例

JavaScript/Node.js

const WebSocket = require('ws');

// WebSocket 接続を作成
const ws = new WebSocket('wss://api.accunote.ai/reco');

ws.on('open', () => {
  // 認証メッセージを送信
  ws.send(JSON.stringify({
    type: 'connect',
    token: 'ak_your_api_key_here'
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);

  if (message.type === 'connected') {
    console.log('接続成功');

    // 認識開始メッセージを送信
    ws.send(JSON.stringify({
      type: 'start',
      config: {
        sampleRate: 16000,
        channels: 1,
        encoding: 'opus',
        language: 'ja-JP'
      }
    }));

    // 音声データを送信（例）
    // ws.send(opusAudioData);
  }

  if (message.type === 'recognition') {
    console.log('認識結果:', message.result.text);
  }
});

// ハートビート
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({
      type: 'ping',
      timestamp: Date.now()
    }));
  }
}, 30000);

Python

import asyncio
import websockets
import json

async def recognize():
    uri = "wss://api.accunote.ai/reco"

    async with websockets.connect(uri) as websocket:
        # 認証
        await websocket.send(json.dumps({
            "type": "connect",
            "token": "ak_your_api_key_here"
        }))

        # 接続確認を受信
        response = await websocket.recv()
        print(json.loads(response))

        # 認識開始
        await websocket.send(json.dumps({
            "type": "start",
            "config": {
                "sampleRate": 16000,
                "channels": 1,
                "encoding": "opus",
                "language": "ja-JP"
            }
        }))

        # 音声データを送信し結果を受信
        # ...

asyncio.run(recognize())

⚠️ エラー処理

サーバーはエラーメッセージを返します：

{
  "type": "error",
  "message": "エラー説明"
}

よくあるエラー

エラーメッセージ	原因	解決方法
未認証：認証情報がありません	認証メッセージを送信していない	接続後すぐに connect メッセージを送信
未認証：無効なアクセスキー	API Key が無効または期限切れ	API Key が正しいか確認
ハートビートタイムアウト	90 秒間メッセージを送信していない	定期的に ping または音声データを送信
認識サービスが利用できません	サーバーが混雑している	しばらく待ってから再試行

📊 使用制限

• 単一 WebSocket 接続の最大持続時間：60 分
• 音声データパケットサイズ：60ms 音声チャンク推奨
• サポートされている音声形式：Opus エンコード、16kHz サンプリングレート、モノラル
• 同時接続数：ご利用のプランによります