API Reference

Speech To Text · HTTP Stream

POSThttps://api.shabd.tech/v1/speech-to-text/stream

Transcribes spoken audio, streamed as NDJSON — one stt line per partial transcript, ending with a completed: true line.

Headers

  • x-api-keystringrequired

    API Key for authentication

    Example:
    <your-api-key>
  • Content-Typestringrequired

    Content type of the request body

    Example:
    multipart/form-data
  • x-request-idstringrequired

    Unique request ID in UUID format

    Example:
    550e8400-e29b-41d4-a716-446655440000

Request bodymultipart/form-data

  • filefileoptional

    Audio file in WAV or PCM format. Optional when audioUrl is supplied.

  • audioUrlstringoptional

    Public http(s) URL to fetch the audio from, as an alternative to uploading file. Exactly one of file or audioUrl is required; if both are sent the uploaded file wins. The URL must be publicly reachable and the downloaded audio is subject to the same size limit as an upload.

    Example:
    https://example.com/audio/sample.wav
  • languagestringrequired

    Language of the speech, or "auto" to detect it from the audio. If "auto" is used, the detected language will be returned in the response.

    Example:
    english
  • sampleRatenumberoptional

    Sample rate of the audio in Hz (default 16000)

    Example:
    16000
  • projectIdstringoptional

    Optional project identifier

    Example:
    <your-project-id-here>

Responses

  • 200NDJSON stream — one stt JSON object per line, newline-separated.
    lineExample
    chunk{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "mode": "stt", "status": true, "completed": false, "chunk": 1, "transcript": "hello world", "language": "english", "start": 0.0, "end": 2.0 }
    final{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "mode": "stt", "status": true, "completed": true, "chunk": 5, "transcript": "", "language": "english", "start": null, "end": null }

    On failure a single error line is sent: { "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": false, "completed": false, "message": "An unexpected error occurred. Please try again later." }

    Bodyapplication/x-ndjson

    • requestIdstringoptional
      Example:
      550e8400-e29b-41d4-a716-446655440000
    • modestringoptional
      Example:
      stt
    • statusbooleanoptional
      Example:
      true
    • completedbooleanoptional
      Example:
      false
    • chunkintegeroptional
      Example:
      1
    • transcriptstringoptional
      Example:
      hello world
    • languagestringoptional

      Language of the transcript (the detected language when "auto" was sent)

      Example:
      english
    • startnumber or nulloptional
      Example:
      0
    • endnumber or nulloptional
      Example:
      2

    Example response

    {  "requestId": "550e8400-e29b-41d4-a716-446655440000",  "mode": "stt",  "status": true,  "completed": false,  "chunk": 1,  "transcript": "hello world",  "language": "english",  "start": 0,  "end": 2}
  • 400Bad Request

    Bodyapplication/json

    • statusbooleanoptional
      Example:
      false
    • messagestringoptional
      Example:
      Invalid input parameters.

    Example response

    {  "status": false,  "message": "Invalid input parameters."}
  • 401Unauthorized Access

    Bodyapplication/json

    • statusbooleanoptional
      Example:
      false
    • messagestringoptional
      Example:
      Unauthorized access.

    Example response

    {  "status": false,  "message": "Unauthorized access."}
  • 403Usage Limit Exceeded

    Bodyapplication/json

    • statusbooleanoptional
      Example:
      false
    • messagestringoptional
      Example:
      Limit Exceeded

    Example response

    {  "status": false,  "message": "Limit Exceeded"}
  • 500Internal server error

    Bodyapplication/json

    • statusbooleanoptional
      Example:
      false
    • messagestringoptional
      Example:
      An unexpected error occurred. Please try again later.

    Example response

    {  "status": false,  "message": "An unexpected error occurred. Please try again later."}