SenseVoice ASR (Speech-to-Text)

SenseVoice ASR is an ASR (speech-to-text) service packaged based on SenseVoice.cpp, running within the AI Pod. The service domain name inside the AI Pod is asr-ai. It provides an OpenAI Audio API-style interface for speech-to-text transcription, enabling backend services, frontend applications, or scripts to upload audio files via HTTP and retrieve transcribed text.

Service Endpoint

API Documentation:
Service Address:
Health Check:
Transcription Endpoint:

Access format after deployment in the AI Pod:

Service Address:https://asr-ai.${LAZYCAT_BOX_DOMAIN}
API Documentation: https://asr-ai.${LAZYCAT_BOX_DOMAIN}/docs
Health Check: https://asr-ai.${LAZYCAT_BOX_DOMAIN}/health
Transcription Interface: https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions

Health Check

`GET /health`

This endpoint is used to verify the availability of the ASR HTTP service.

Request:

bash

curl https://asr-ai.${LAZYCAT_BOX_DOMAIN}/health

Response example:

json

{
  "status": "ok"
}

Transcription Interface

`POST /v1/audio/transcriptions`

This interface accepts an audio file and returns transcription results. The request must use multipart/form-data.

The service first uses ffmpeg to convert the uploaded audio into a 16 kHz, single-channel wav, then performs SenseVoice inference. Therefore, the actual supported audio formats depend on the container image's ffmpeg decoding capabilities. Common formats such as wav, mp3, m4a, mp4, webm, flac, and ogg can typically be uploaded directly.

Parameters	Type	Required	Description
`file`	file	Yes	Pending audio file to be transcribed
`language`	string	no	Voice language, default `auto`. Supports `auto` / `zh` / `en` / `ja` / `ko` / `yue`, invalid values are handled as `auto`.
`response_format`	string	no	Default `json`. Pass `text` returns plain text; pass any other value returns JSON
`token_timestamps`	string	no	When transmitting `true`, the segmented result contains `words` timestamp information.
`split_on_word`	string	no	When transmitting `true`, it also includes `words` timestamp information.

The current service does not provide srt / vtt subtitle output, nor does it offer progress / progress_format progress event stream. When subtitles are required, it is recommended to generate them using the JSON field segments.

`response_format`	Content-Type	Description
`json`	`application/json`	Default format, including `text` and `segments`
`verbose_json`	`application/json`	Compatible with common invocation patterns, returns the same type of JSON structure in practice.
`text`	`text/plain; charset=utf-8`	Only return the transcribed text.

JSON response example:

json

{
  "text": "欢迎使用算力舱语音转写服务。",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 2.4,
      "text": "欢迎使用算力舱语音转写服务。"
    }
  ]
}

After enabling token_timestamps=true or split_on_word=true, segments will additionally include words:

json

{
  "id": 0,
  "start": 0.0,
  "end": 2.4,
  "text": "欢迎使用算力舱语音转写服务。",
  "words": [
    {
      "word": "欢迎",
      "text": "欢迎",
      "start": 0.12,
      "end": 0.42,
      "probability": 0.98
    }
  ]
}

Error response example:

json

{
  "error": "multipart field 'file' is required"
}

Common Errors:

HTTP status codes	Scenario
`400`	Not used `multipart/form-data`, missing `file` field, or `ffmpeg` cannot convert uploaded audio
`500`	Failed to write temporary file

Call Examples

JSON Transcription

bash

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "language=auto" \
  -F "response_format=json"

Plain text transcription

bash

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "response_format=text"

Timestamped Transcription

bash

curl -fsS -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/audio.wav" \
  -F "language=zh" \
  -F "token_timestamps=true"

Recommended Calling Flow

Prepare audio files. For video files, it is recommended to extract the audio first before uploading.
Upload multipart/form-data to /v1/audio/transcriptions.
language Unknown transmission auto; known language transmission zh / en / ja / ko / yue.
When processing segmented data, use default JSON; when only displaying text, use response_format=text.
When word-level timestamps are required, pass token_timestamps=true or split_on_word=true.

Backend Environment Variables

In business services dependent on ASR, the ASR base URL can be configured as:

yaml

services:
  convert:
    environment:
      - ASR_URL=https://asr-ai.${LAZYCAT_BOX_DOMAIN}
      - HOMEDIR=/lzcapp/run/mnt/home

ASR_URL: ASR service base address, business code concatenated with /v1/audio/transcriptions.
HOMEDIR: root path for business file read/write, configured according to application requirements.

Frontend matches asr-ai domain.

const asrUrl = (path = "/v1/audio/transcriptions") => {
  const currentHost = window.location.host;
  const protocol = window.location.protocol;
  const host = currentHost.replace(/^([^.]+)/, "asr-ai");

  return `${protocol}//${host}${path}`;
};

Independent Deployment Usage

Select the corresponding image based on the device. The AGX Orin uses image -agxorin, and the Thor T5000 uses image -thor.

AGX Orin

yml

services:
  asr:
    image: registry.lazycat.cloud/catdogai/lzc-aipod-sensevoiceasr:0.2.0-sensevoice-small-q4k-agxorin
    ports:
      - 3000:3000
    environment:
      - PORT=3000
      - SENSEVOICE_MODEL=/opt/sensevoice-models/sense-voice-small-q4_k.gguf
      - SENSEVOICE_LANGUAGE=auto
      - SENSEVOICE_THREADS=4
      - SENSEVOICE_USE_ITN=true
      - OMP_NUM_THREADS=1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 30s
      retries: 100
      start_period: 30s

Thor T5000

yml

services:
  asr:
    image: registry.lazycat.cloud/catdogai/lzc-aipod-sensevoiceasr:0.2.0-sensevoice-small-q4k-thor
    ports:
      - 3000:3000
    environment:
      - PORT=3000
      - SENSEVOICE_MODEL=/opt/sensevoice-models/sense-voice-small-q4_k.gguf
      - SENSEVOICE_LANGUAGE=auto
      - SENSEVOICE_THREADS=4
      - SENSEVOICE_USE_ITN=true
      - OMP_NUM_THREADS=1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 30s
      retries: 100
      start_period: 30s

Boot:

bash

docker compose up -d
curl http://127.0.0.1:3000/health

After startup, you can access http://127.0.0.1:3000/docs to view the built-in API documentation of the service.

Service Environment Variables

Variable	Default value	Description
`PORT`	`3000`	HTTP listening port
`SENSEVOICE_MODEL`	`/opt/sensevoice-models/sense-voice-small-q4_k.gguf`	SenseVoice GGUF model path
`SENSEVOICE_LANGUAGE`	`auto`	Default recognized language
`SENSEVOICE_THREADS`	`4`	Inference thread count
`SENSEVOICE_USE_GPU`	`true`	Whether to enable GPU
`SENSEVOICE_USE_ITN`	`true`	Whether to enable reverse text regularization, including punctuation processing
`SENSEVOICE_USE_PREFIX`	`false`	Whether to output SenseVoice prefix information
`OMP_NUM_THREADS`	`1`	OpenMP thread count

SenseVoice ASR is enabled by default with SENSEVOICE_USE_ITN=true, which performs text normalization and punctuation processing.

SenseVoice ASR (Speech-to-Text) ​

Service Endpoint ​

Health Check ​

GET /health ​

Transcription Interface ​

POST /v1/audio/transcriptions ​

Call Examples ​

JSON Transcription ​

Plain text transcription ​

Timestamped Transcription ​

Recommended Calling Flow ​

Backend Environment Variables ​

Independent Deployment Usage ​

AGX Orin ​

Thor T5000 ​

Service Environment Variables ​

Related Services ​

SenseVoice ASR (Speech-to-Text)

Service Endpoint

Health Check

`GET /health`

Transcription Interface

`POST /v1/audio/transcriptions`

Call Examples

JSON Transcription

Plain text transcription

Timestamped Transcription

Recommended Calling Flow

Backend Environment Variables

Independent Deployment Usage

AGX Orin

Thor T5000

Service Environment Variables

Related Services