Search VisionStory documentation

No documentation matched “”.

Try a feature or resource name such as , , or .

VisionStoryDevelopers
Get API key

Guide

Audio Transcription and Alignment API

Transcribe WAV or MP3 speech to text, get word-level timestamps, identify speakers, generate SRT subtitles, or align a known script with audio using the VisionStory API.

The VisionStory Audio Understanding API turns speech audio into text, subtitles, and precise word timing. Use transcription when you need speech-to-text, speaker labels, or SRT output. Use alignment when you already know the spoken script and need accurate timestamps for every word.

Both endpoints are synchronous, accept WAV or MP3 audio up to 15 MB, and charge 1 credit per started 5 minutes only when processing succeeds. An active Pro plan or above is required; no separate beta allowlist is needed.

Audio transcription and alignment endpoints

MethodPathUse it for
POST/api/v1/audio/transcribeSpeech-to-text with optional speaker diarization and SRT subtitles
POST/api/v1/audio/alignWord-level timing when the exact spoken text is already known

Each request accepts exactly one audio source inside audio: a reusable asset_id, a public url, or base64 inline_data.

Transcribe audio to text

Set diarize: true to label speaker turns and srt: true to include a ready-to-save subtitle track:

Shell
curl -s -X POST \
  -H "X-API-Key: $VISIONSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio":{"url":"https://example.com/interview.mp3"},"diarize":true,"srt":true}' \
  https://openapi.visionstory.ai/api/v1/audio/transcribe

The response contains the full transcript, detected language, word timestamps, optional speaker labels, optional SRT, duration, and credits charged:

JSON
{
  "data": {
    "text": "Welcome to VisionStory.",
    "language": "en",
    "words": [
      { "text": "Welcome", "start_sec": 0.0, "end_sec": 0.48, "speaker": "speaker_0" }
    ],
    "srt": "1\n00:00:00,000 --> 00:00:01,200\nWelcome to VisionStory.",
    "duration_sec": 1.2,
    "cost_credit": 1
  }
}

With the Python SDK:

Python
from pathlib import Path
from visionstory import VisionStoryClient

client = VisionStoryClient.from_env()
transcript = client.transcribe_audio(
    audio_file=Path("interview.mp3"),
    diarize=True,
    srt=True,
)
Path("interview.srt").write_text(transcript["srt"], encoding="utf-8")

Align a script with audio

Alignment is useful after text-to-speech generation, dubbing, or voice-over production. Send the exact text spoken in the audio:

Shell
curl -s -X POST \
  -H "X-API-Key: $VISIONSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio":{"asset_id":"YOUR_AUDIO_ASSET_ID"},"text":"Welcome to VisionStory."}' \
  https://openapi.visionstory.ai/api/v1/audio/align

The response returns words, duration_sec, and cost_credit. Each word includes text, start_sec, and end_sec.

Use the CLI or MCP

Shell
visionstory transcribe --audio-file interview.mp3 --diarize --srt --output interview.srt
visionstory align --audio-url https://example.com/speech.mp3 --text "Welcome to VisionStory."

MCP clients expose the same workflows as transcribe_audio and align_audio. The local stdio MCP accepts file paths, URLs, or asset IDs. The remote MCP accepts public URLs or reusable asset IDs because it cannot read files from your computer.

Limits and billing

  • Audio input: WAV or MP3, up to 15 MB.
  • Processing: synchronous; use short audio where possible to avoid client or proxy timeouts.
  • Billing: 1 credit per started 5 minutes, charged only on success.
  • Concurrency: requests beyond the per-key synchronous limit are rejected rather than queued.
  • Reuse: upload frequently used audio through the Assets API and pass its asset_id.
  • Text to Speech — generate MP3 speech, then align it for subtitles.
  • Voices — filter public voices or clone a reusable voice.
  • Python SDK — call transcription and alignment from Python.
  • API reference — exact request and response schemas.