avacast
English無料で始める

API リファレンス

ベース URL は https://api.avacast.jp。 リクエストもレスポンスも JSON、フィールド名は snake_case、日時は ISO 8601（UTC）です。

認証

2 種類あります。用途が違うので混ぜないでください。

種類どこで使うかできること
sk_live_サーバーのみ全操作
client_tokenブラウザそのセッションの発話と中断だけ

どちらも Authorization: Bearer <値> で渡します。API キーをブラウザに出さないでください。セッション作成時に返る client_token だけを渡します。

# レート制限は成功時もヘッダで残量が返ります
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 118
X-RateLimit-Limit-Hour: 3000
X-RateLimit-Remaining-Hour: 2941
Retry-After: 42            # 429 のときのみ

ブラウザ SDK

WebRTC の接続と発話イベントの購読をまとめた小さな SDK です。npm には出しておらず、 avacast のドメインから読み込みます（パスに版が入っています。互換を壊す変更は v2 にします）。

<video id="avatar" autoplay playsinline></video>
<script type="module">
  import { AvacastSession } from 'https://avacast.jp/sdk/v1.js';

  // client_token はサーバーで作ったセッションから受け取る (API キーは出さない)
  const session = new AvacastSession(clientToken);
  session.on('session.ready', () => session.attach(document.getElementById('avatar')));
  session.on('speak.ended', () => askNextQuestion());
  await session.start();
  session.speak('ご相談ありがとうございます。');
</script>

module を使えない場合は https://avacast.jp/sdk/v1.iife.js を読むとグローバルの Avacast.AvacastSession になります。イベントは session.ready / speak.started / speak.ended / speak.interrupted / session.ended。

POST/api/v1/sessionsAPI キー

セッションを作る

アバターの枠を確保し、ブラウザへ渡すトークンを返します。

パラメータ型説明
avatar_id必須string使うアバター。管理画面で確認できます。
voice.languagestring読み上げ言語。未対応の値は ja になります（エラーにしません）。既定 ja
voice.voice_idstring声の指定。edge-tts の音声名 (例 ja-JP-NanamiNeural) か、gemini:<声>:<性別>:<年代>:<調子> (例 gemini:Gacrux:female:50:calm。調子は bright/clear/soft/warm/calm/gentle/deep/friendly) か gemini:<声>:<話し方の自由文>。省略するとアバターの既定の声、それも無ければ言語と性別に合う声を選びます。
voice.speednumber発話速度。0.8〜1.2 に丸めます（範囲外でもエラーにしません）。既定 1.0
idle_timeout_secondsnumber無発話で自動終了するまでの秒数。30〜1800 に丸めます。既定 180
metadataobject自由なラベル。利用状況の絞り込みに使えます。

REQUEST

curl -X POST https://api.avacast.jp/api/v1/sessions \
  -H "Authorization: Bearer $AVACAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "avatar_id": "avt_xxxxxxxx", "voice": { "language": "ja", "speed": 0.9 } }'

RESPONSE

{
  "session_id": "ses_xxxxxxxx",
  "client_token": "eyJhbGciOi...",
  "webrtc": {
    "signaling_url": "https://.../offer",
    "events_url": "https://.../events",
    "ice_servers": [{ "urls": "turn:...", "username": "...", "credential": "..." }]
  },
  "expires_at": "2026-09-05T12:30:00.000Z"
}
  • client_token と webrtc（signaling_url / ice_servers）はブラウザへ渡してよい値です。API キーは渡さないでください。
  • ice_servers は RTCPeerConnection にそのまま渡してください（JS SDK は自動で使います）。
  • events_url は発話イベントの SSE です。`?token=<client_token>` を付けて EventSource で開くと speak.started / speak.ended / speak.interrupted / session.ended が届きます（JS SDK は自動で購読します）。
  • 1 セッションの最大長はプランで決まります（Free 5 分 / Starter 15 分 / Standard 30 分 / Business 60 分）。expires_at に入ります。延長はできないので、長い対話では張り直してください。
  • 課金はセッションが開いていた時間（接続時間）で数えます。閉じ忘れは請求に乗るので、終わったら DELETE してください。無発話が続けば自動で閉じます。
  • Idempotency-Key ヘッダに対応。再送で GPU の枠を二重に掴むのを防げます。
POST/api/v1/sessions/:id/speakAPI キー

喋らせる

テキストをキューに積みます。前の発話の完了を待つ必要はありません。

パラメータ型説明
text必須string読み上げるテキスト。1,000 文字まで。

REQUEST

curl -X POST https://api.avacast.jp/api/v1/sessions/ses_xxxxxxxx/speak \
  -H "Authorization: Bearer $AVACAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "ご相談ありがとうございます。" }'

RESPONSE

{ "utterance_id": "utt_xxxxxxxx", "status": "queued", "queue_length": 1 }
  • 喋った長さで請求は変わりません（課金は接続時間）。ただし発話中はアイドル判定が止まります。
  • キューは 1 セッションあたり 20 件まで。超えると 429 queue_full。
  • Idempotency-Key ヘッダに対応。再送しても同じ発話は二度流れません。
POST/api/v1/sessions/:id/interruptAPI キー

中断する

再生中の発話を止め、キューの未再生分を破棄します。

REQUEST

curl -X POST https://api.avacast.jp/api/v1/sessions/ses_xxxxxxxx/interrupt \
  -H "Authorization: Bearer $AVACAST_API_KEY"

RESPONSE

{ "interrupted_utterance_id": "utt_xxxxxxxx", "discarded_count": 2 }
  • 中断しても請求は変わりません（課金は接続時間で数えるため）。
GET/api/v1/sessions/:idAPI キー

セッションの状態

いまの状態、接続時間、累計の発話時間を返します。デバッグと監視向け。

REQUEST

curl https://api.avacast.jp/api/v1/sessions/ses_xxxxxxxx \
  -H "Authorization: Bearer $AVACAST_API_KEY"

RESPONSE

{
  "session_id": "ses_xxxxxxxx",
  "status": "active",
  "end_reason": null,
  "queue_length": 0,
  "connected_seconds": 312,
  "total_speak_ms": 7500,
  "expires_at": "2026-09-05T12:30:00.000Z"
}
  • connected_seconds が請求の根拠です。total_speak_ms は実際に音声が鳴っていた時間で、参考値です。
DELETE/api/v1/sessions/:idAPI キー

セッションを終える

GPU の枠を解放します。終了済みに再度呼んでもエラーにしません。

REQUEST

curl -X DELETE https://api.avacast.jp/api/v1/sessions/ses_xxxxxxxx \
  -H "Authorization: Bearer $AVACAST_API_KEY"

RESPONSE

{ "session_id": "ses_xxxxxxxx", "status": "ended", "connected_seconds": 312, "total_speak_ms": 7500 }
  • 呼ばなくても、プランごとの最大長と無発話（既定 180 秒）で自動的に閉じます。
  • 自動で閉じた場合、接続時間は「閉じるべきだった時刻」までで数えます。
GET/api/v1/avatarsAPI キー

アバター一覧

使えるアバターを返します。プリセットと自社専用のものが含まれます。

REQUEST

curl https://api.avacast.jp/api/v1/avatars \
  -H "Authorization: Bearer $AVACAST_API_KEY"

RESPONSE

{
  "data": [
    { "id": "avt_xxxxxxxx", "name": "案内役A", "languages": ["ja", "en"], "is_preset": true }
  ]
}
GET/api/v1/usageAPI キー

当月の利用状況

請求の前に自分で確認できます。管理画面と同じ数字です。

REQUEST

curl https://api.avacast.jp/api/v1/usage \
  -H "Authorization: Bearer $AVACAST_API_KEY"

RESPONSE

{
  "period": { "start": "...", "end": "..." },
  "connected_seconds": 18640,
  "total_speak_seconds": 4820,
  "session_count": 312,
  "utterance_count": 2914,
  "limits": { "concurrency": 10, "monthly_connected_seconds": null }
}
  • connected_seconds が請求の根拠です。開いているセッションの分も今この瞬間まで含みます。
  • limits.monthly_connected_seconds に達すると、新しいセッションの作成が 402 payment_required になります。
POST/api/v1/client/sessions/:id/speakclient_token

ブラウザから喋らせる

client_token で認証します。会話ロジックがフロントにある場合、サーバーを経由せずに済みます。

パラメータ型説明
text必須string読み上げるテキスト。1,000 文字まで。

REQUEST

await fetch('https://api.avacast.jp/api/v1/client/sessions/ses_xxxxxxxx/speak', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${clientToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'ご相談ありがとうございます。' }),
});

RESPONSE

{ "utterance_id": "utt_xxxxxxxx", "status": "queued", "queue_length": 1 }
  • トークンは 1 セッションにしか効きません。URL のセッション ID を書き換えても 401 になります。
  • 中断は /api/v1/client/sessions/:id/interrupt です。

エラー

code で分岐してください。message は改善のために変わります。

{
  "error": {
    "code": "session_not_found",
    "message": "Session ses_xxxxxxxx was not found."
  }
}
HTTPcode意味
400invalid_requestパラメータ不正（文字数超過、必須項目の欠落など）
401invalid_api_keyAPI キーが不正、失効済み、またはアカウント停止中
401invalid_client_tokenトークンが不正、期限切れ、または別セッションのもの
402payment_required月間の発話上限に到達
404session_not_foundセッションが存在しない
404avatar_not_foundアバターが存在しない、または使えない
409session_ended終了済み・期限切れのセッションへの操作
409idempotency_conflict同じ Idempotency-Key で異なる内容を送信
429rate_limited呼び出し頻度の制限。Retry-After 秒待つ
429concurrency_limit同時セッション数の上限。どれかを閉じる
429queue_full発話キューが上限。speak.ended を待つか interrupt
503gpu_unavailableGPU の空きがない