Transcribe audio — VisionStory API

Transcribe speech audio to text with word-level timestamps; optionally detect speaker turns (diarize) or render an SRT subtitle track (srt). Billing: 1 credit per started 5 minutes of audio, charged only on success. Synchronous — audio up to 30 minutes. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

audioMediaRefrequired

A media reference — provide exactly one of: asset_id (from the asset library, reusable across requests), url (one-off public URL), or inline_data (one-off base64, not stored).

asset_idstring | nullnullable

Asset ID from POST /api/v1/asset; use for materials reused across requests.

inline_dataInlineDataModel | nullnullable

Inline base64 media data for one-off use; not added to your asset library.

datastringrequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

mime_typestringrequired

MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

urlstring | nullnullable

Publicly accessible media URL for one-off use; not added to your asset library.

diarizeboolean

Set true to detect speaker turns; each word then carries a speaker label.

Default: false

srtboolean

Set true to also return an SRT subtitle rendering of the transcript.

Default: false

Responses

200Successful Response

application/json

dataTranscribeResponse | nullrequirednullable

The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.

cost_creditinteger

Credits charged for this request.

Default: 0

duration_secnumber

Duration of the input audio in seconds.

Default: 0

languagestring

Detected language code of the audio, e.g. en; may be empty.

Default:

srtstring

SRT subtitle text; empty unless srt: true was requested.

Default:

textstringrequired

Full transcript text.

wordsWordDto[]

Word-level timestamps.

end_secnumberrequired

Word end time in seconds.

speakerstring | nullnullable

Speaker label, present only when diarize was requested.

start_secnumberrequired

Word start time in seconds.

textstringrequired

The word as written.

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError response. All failures share one envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (useful for AI agents).

application/json

errorErrorDetailrequired

codeintegerrequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

detailsstring | nullnullable

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullnullable

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.