Speech to text

Transcribe speech audio into text with utterance timestamps, optional speaker diarization, non-verbal audio-event tags, and ready-to-use JSON, SRT, and VTT subtitle files.

Primary agent path

Use the Universal Skill with the MCP tool beatra.audio.transcribe. The tool is billable and returns an asynchronous task.

1. Upload local audio with beatra.assets.upload and use the returned artifact_id (or pass an https_url).
2. When language breadth, non-verbal event tagging, or price matters, call beatra.models.list with capability: "speech_to_text". Otherwise omit model or pass "auto" (doubao-seed-asr-2.0 by default, or automatically routed to elevenlabs-scribe-v3 when tag_audio_events: true or num_speakers is requested).
3. Create one opaque client_request_id and submit the final arguments once.
4. Poll the returned task with beatra.tasks.get until it is terminal, and read the full transcript from that single-task response.

AI guide

Tool arguments

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

• audio (required; source accepted as an input alias on both MCP and REST): an artifact reference ({"type": "artifact", "artifact_id": "..."}) or HTTPS URL ({"type": "https_url", "url": "https://..."}). Accepted formats include MP3, WAV, M4A, AAC, FLAC, OGG, and Opus. Duration must be between 0.5 seconds and 3,600 seconds (60 minutes), and file size at most 100 MiB. Audio longer than 60 minutes is rejected before billing with 422 invalid_request (details.reason: "audio_too_long"; split longer recordings first with beatra.audio.process operation: "trim" — see audio processing).
• model (optional, default "auto"): "auto", "doubao-seed-asr-2.0", or "elevenlabs-scribe-v3".
• language (optional, default "auto"): "auto" for automatic language detection, or a BCP-47 / ISO-639-1 tag such as "zh", "yue", "en", or "ja".
• diarize (optional, boolean, default false): label speaker turns across segments[] (speaker_0, speaker_1, …).
• num_speakers (optional, integer 1–32): expected speaker count hint on elevenlabs-scribe-v3; passing num_speakers implies diarize: true and automatically upgrades model: "auto" to elevenlabs-scribe-v3 when available.
• tag_audio_events (optional, boolean, default false): tag non-verbal audio events such as laughter, applause, and music on elevenlabs-scribe-v3. When model is "auto", passing tag_audio_events: true automatically selects elevenlabs-scribe-v3 if available; passing tag_audio_events: true or num_speakers with an explicit model: "doubao-seed-asr-2.0" attaches a non-blocking option_ignored warning.
• subtitles (optional, boolean, default true): generate and persist the JSON, SRT, and VTT subtitle bundle on Beatra CDN at no extra charge.
• model_options (optional, object): forward-compatible bag for model-specific extension options.

Models and cost

beatra.models.list with capability: "speech_to_text" is the live source for selectable models, supported controls, and prices.

Transcription is prepaid by started input minute (ceil(duration_seconds / 60)), with a per-request minimum:

Result and subtitles

When the task succeeds, output contains the full transcript, utterance-level segments, optional audio events, and the subtitle bundle:

{
  "type": "speech_to_text",
  "model": "doubao-seed-asr-2.0",
  "text": "大家好，欢迎来到今天的播客。谢谢邀请！",
  "language": "zh",
  "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 uses the exact same files.{json, srt, vtt} structure as text to speech subtitles, so downstream video composition and captioning pipelines consume both without format conversion.
• Silent or speech-free audio is a valid observation, not an error: the task succeeds with text: "", segments: [], and subtitles: null.
• In task list views (GET /v1/tasks), long transcripts return a bounded preview marked truncated: true. Always read beatra.tasks.get or GET /v1/tasks/{task_id} for the complete text and segments[].

Task status and recovery

queued and running are not failures. Keep polling the same task_id; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same client_request_id. If any input changes, use a new ID. Failed tasks automatically refund the reserved credits.

REST API

Direct protocol integrations may use POST /v1/audio/transcriptions with a stable Idempotency-Key header and the shared task endpoints. Follow the generated API reference. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.