# 音声文字起こし
> 音声をテキストに文字起こしし、話者分離、タイムスタンプ、非言語イベントタグ、JSON/SRT/VTT 字幕を生成します。

音声をテキストに文字起こしし、発話ごとのタイムスタンプ、任意の話者分離（ダイアライゼーション）、非言語オーディオイベントタグ、そのまま使える 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 ガイド

AI integration guide: https://docs.beatra.ai/llms/audio-speech-to-text.md

## ツール引数

```json
{
  "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"` で分割してください。[オーディオ処理](https://docs.beatra.ai/ja/docs/capabilities/speech/audio-processing)を参照）。
- `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 リクエストあたりの最低料金があります。

| モデル | 単価 | 最低料金 | 特徴 |
| --- | --- | --- | --- |
| `doubao-seed-asr-2.0`（`auto` 既定） | `15 クレジット` / 切り上げ分 | `60 クレジット`（`<= 4 分`） | 中国語（標準語・方言）、英語、日本語、多言語の高精度認識。話者分離とタイムスタンプに対応。 |
| `elevenlabs-scribe-v3` | `21 クレジット` / 切り上げ分 | `61 クレジット`（`<= 2 分`） | 90 以上の言語、最大 32 人の話者分離（`num_speakers`）、タイムスタンプ、非言語 `tag_audio_events`（`(laughter)`、`(applause)`、`(music)` など）に対応。 |

## 結果と字幕

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

```json
{
  "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` は[音声合成の字幕](https://docs.beatra.ai/ja/docs/capabilities/speech/text-to-speech#字幕)とまったく同じ `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 リファレンス](https://docs.beatra.ai/ja/docs/api-reference)を参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。