ASR API Reference

The Shisa ASR API transcribes base64-encoded audio into text with a single JSON request. This page documents the endpoint, its request parameters, the success response, and error handling.

Endpoint

POST https://api.shisa.ai/asr/srt/audio_llm

Authenticate with a bearer token containing your full shsk: API key:

Authorization: Bearer YOUR_API_KEY

The request body is JSON and the server auto-detects the audio format from its binary header.

Request parameters

Parameter	Type	Required	Description
audio	string	Required	Base64-encoded audio data (WAV, OGG, MP3, or FLAC).
language	string	Optional	Language code (e.g. "ja", "en"). Omit for automatic language detection (LID).
hotwords	string[]	Optional	Array of words/phrases to boost recognition accuracy for domain-specific terms.
temperature	float	Optional	Sampling temperature. Lower values make output more deterministic. Default: 0.0.
top_p	float	Optional	Nucleus sampling parameter. Controls diversity of output. Default: 0.85.
frequency_penalty	float	Optional	Penalizes frequent tokens to reduce repetition. Default: 0.5.
repetition_penalty	float	Optional	Penalizes token repetition; values above 1.0 discourage repetition. Default: 1.05.
vad	integer or string	Optional	Voice activity detection: 0/"off" (default), 1/"on", or "segments" for timestamped chunks.
min_silence_gap	integer	Segments only	Silence in milliseconds that creates a split. Default: 400.
segment_padding	integer	Segments only	Padding added to segment edges in milliseconds. Default: 100; range: 0–5000.
initial_segment_padding_ms	integer	Segments only	Leading pre-roll for the first segment in milliseconds. Default: 1500; range: 0–5000.
speech_pad_ms	integer	Segments only	Speech timestamp padding in milliseconds. Default: 200.
min_segment_duration	float	Segments only	Minimum segment duration before merging, in seconds. Default: 1.5.

note

Only audio is required. With the recommended top-level audio request shape, language is auto-detected and vad defaults to "off". The field is named vad; vad_filter is not supported.

Legacy request shape

Legacy requests using messages default vad to 1. Their OpenAI-style model field is accepted for compatibility but ignored; the deployment selects the ASR backend and model.

Success response

A successful request returns a JSON object with the transcription, the detected or specified language, and a confidence score:

{
  "text": "こんにちは、シサAIです。",
  "language": "ja",
  "confidence": 0.98
}

Field	Description
text	The transcribed text from the audio.
language	The detected or specified language code.
confidence	Transcription confidence score, from 0 to 1.

Segments response

With vad: "segments", the response contains timestamped chunks instead of a top-level text field:

{
  "language": "ja",
  "confidence": 1.0,
  "segments": [
    {
      "start": 0.0,
      "end": 4.78,
      "text": "こんにちは、シサAIです。"
    }
  ]
}

segments[].start and segments[].end are the emitted audio-chunk boundaries in seconds after padding and merging.

Error handling

Router-generated errors commonly include context, a numeric code, a name, and an error string:

{
  "context": ["authMiddleware"],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

Error codes

Status	Cause
400	Invalid JSON, base64/audio, language, VAD settings, or session ID. Most ASR body validation is backend-defined.
401	Missing or invalid API key.
403	The key is valid but does not have batch-ASR access.
404	The routed ASR service/provider is not registered.
429	Global key limit, ASR-specific limit, or backend capacity reached. Retry with backoff.
500	Router-side internal or post-processing failure.
502	The router could not reach the selected backend.
Backend status	Backend errors are forwarded with the backend's status and response body.

Exact backend error fields and messages are not part of the router contract. See Errors for robust error parsing.

Next steps

• Make a working request in the Quickstart.
• Review supported formats and language selection in Audio & languages.
• See how usage is billed on Pricing.