音声文字起こし

音声をテキストに文字起こしし、発話ごとのタイムスタンプ、任意の話者分離（ダイアライゼーション）、非言語オーディオイベントタグ、そのまま使える JSON・SRT・VTT 字幕ファイルを返します。

Agent の主経路

Universal Skill から MCP ツール beatra.audio.transcribe を使います。このツールは課金対象で、非同期タスクを返します。

1. ローカルの音声ファイルを beatra.assets.upload でアップロードし、返された artifact_id を使います（または https_url を直接渡します）。
2. 対応言語の広さ、非言語イベントのタグ付け、価格を比較する場合は capability: "speech_to_text" で beatra.models.list を呼びます。それ以外は model を省略するか "auto" を指定します（既定で doubao-seed-asr-2.0 が選ばれ、tag_audio_events: true または num_speakers を指定した場合は利用可能であれば自動的に elevenlabs-scribe-v3 へルーティングされます）。
3. 不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
4. beatra.tasks.get で終端状態までポーリングし、その単一タスク応答から全文を取得します。

AI ガイド

ツール引数

{
  "audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "model": "auto",
  "language": "auto",
  "diarize": true,
  "subtitles": true,
  "client_request_id": "stt-opaque-1"
}

• audio（必須。MCP・REST ともに入力エイリアスとして source も受け付けます）：artifact 参照（{"type": "artifact", "artifact_id": "..."}）または HTTPS URL（{"type": "https_url", "url": "https://..."}）。MP3、WAV、M4A、AAC、FLAC、OGG、Opus を受け付けます。長さは 0.5 秒以上 3,600 秒（60 分）以下、ファイルサイズは 100 MiB 以下です。60 分 を超える音声は課金前に 422 invalid_request（details.reason: "audio_too_long"）で拒否されます（先に beatra.audio.process の operation: "trim" で分割してください。オーディオ処理を参照）。
• model（任意、既定 "auto"）："auto"、"doubao-seed-asr-2.0"、"elevenlabs-scribe-v3" のいずれか。
• language（任意、既定 "auto"）："auto" で自動言語検出、または "zh"、"yue"、"en"、"ja" などの BCP-47 / ISO-639-1 タグを指定します。
• diarize（任意、真偽値、既定 false）：segments[] ごとに話者ラベル（speaker_0、speaker_1 など）を付与します。
• num_speakers（任意、整数 1〜32）：elevenlabs-scribe-v3 における話者数のヒント。指定すると自動的に diarize: true が有効になり、model: "auto" では利用可能な場合 elevenlabs-scribe-v3 が選択されます。
• tag_audio_events（任意、真偽値、既定 false）：elevenlabs-scribe-v3 で拍手や音楽などの非言語オーディオイベントをタグ付けします。model: "auto" で tag_audio_events: true を渡すと利用可能な場合 elevenlabs-scribe-v3 が自動選択され、model: "doubao-seed-asr-2.0" を明示指定して tag_audio_events: true や num_speakers を渡した場合は option_ignored 警告を添えて実行します。
• subtitles（任意、真偽値、既定 true）：追加料金なしで JSON・SRT・VTT の字幕ファイル一式を生成・保存します。
• model_options（任意、オブジェクト）：モデル固有の拡張指定を渡すための前方互換フィールドです。

モデルとコスト

選択可能なモデル、対応コントロール、価格の最新の事実源は capability: "speech_to_text" を指定した beatra.models.list です。

文字起こしは入力音声の切り上げ分数（ceil(duration_seconds / 60)）に基づく前払いで、1 リクエストあたりの最低料金があります。

結果と字幕

タスクが成功すると、output に全文テキスト、発話単位のセグメント、任意のオーディオイベント、字幕バンドルが入ります。

{
  "type": "speech_to_text",
  "model": "doubao-seed-asr-2.0",
  "text": "皆さんこんにちは、本日のポッドキャストへようこそ。お招きいただきありがとうございます！",
  "language": "ja",
  "duration_seconds": 6.4,
  "segments": [
    {
      "text": "皆さんこんにちは、本日のポッドキャストへようこそ。",
      "start_seconds": 0.12,
      "end_seconds": 3.48,
      "speaker_id": "speaker_0"
    },
    {
      "text": "お招きいただきありがとうございます！",
      "start_seconds": 3.85,
      "end_seconds": 5.9,
      "speaker_id": "speaker_1"
    }
  ],
  "audio_events": [],
  "subtitles": {
    "url": "https://cdn.beatra.ai/tenants/.../subtitles.json",
    "format": "json",
    "files": {
      "json": "https://cdn.beatra.ai/tenants/.../subtitles.json",
      "srt": "https://cdn.beatra.ai/tenants/.../subtitles.srt",
      "vtt": "https://cdn.beatra.ai/tenants/.../subtitles.vtt"
    },
    "segment_count": 2
  }
}

• subtitles は音声合成の字幕とまったく同じ files.{json, srt, vtt} 形式のため、後続の動画合成や字幕パイプラインでそのまま利用できます。
• 無音や発話のないオーディオも正常な結果として成功し、text: ""、segments: []、subtitles: null を返します。
• タスク一覧（GET /v1/tasks）では長い書き起こしは truncated: true 付きの要約になります。完全な text と segments[] は beatra.tasks.get または GET /v1/tasks/{task_id} で取得してください。

タスクの状態とリカバリー

queued と running は失敗ではありません。同じ task_id をポーリングし続けてください。作成応答を失った場合は同じ client_request_id で同一の引数を再送し、入力が変わったら新しい ID を使います。失敗したタスクは自動で返金されます。

REST で呼び出す

プロトコル直結の統合では、固定の Idempotency-Key ヘッダーを付けて POST /v1/audio/transcriptions と共有タスクエンドポイントを使えます。生成されたAPI リファレンスを参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。