Skip to content

STT REST APIs

List all available ASR models

1
GET https://api.prosa.ai/v2/speech/stt/models

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[
  {
    "name": "string",
    "label": "string",
    "language": "string",
    "domain": "string",
    "acoustic": "string",
    "channels": 0,
    "samplerate": 0
  }
]

Responses

Status Meaning Description Schema
200 OK Successful Response AsrModelList
401 Unauthorized Unauthorized
403 Forbidden Forbidden ForbiddenError
500 Internal Server Error Internal Server Error InternalServerError

Retrieve ASR jobs

1
GET https://api.prosa.ai/v2/speech/stt

Retrieve all ASR jobs. Request audio data and results are not included in the response.

Parameters

Name In Type Required Description
x-api-key header string true API Key received from Prosa API Console
page query integer false Index of the pagination to return
per_page query integer false Number of elements per page
from_date query string(date) false Filter jobs that are created from the date onward
until_date query string(date) false Filter jobs that are created until the date (the date itself is included)
sort_by query any false Sort the result based on the field
sort_ascend query boolean false Sort the result in ascending order
query_text query string false Find a job with corresponding result text

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "page_count": 1
  },
  "length": 1,
  "data": [
    {
      "job_id": "2fec34e1efb146f7a7431cb35b64550d",
      "status": "complete",
      "created_at": "2019-08-24T14:15:22Z",
      "modified_at": "2019-08-24T14:15:22Z",
      "request": {
        "label": "Meeting Audio 2021-14-06",
        "uri": "https://..."
      },
      "job_config": {
        "model": "stt-general",
        "wait": false,
        "include_filler": false,
        "include_partial_results": false
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Successful Response AsrJobsList
401 Unauthorized Unauthorized
403 Forbidden Forbidden ForbiddenError
422 Unprocessable Entity Validation Error RequestValidationError
500 Internal Server Error Internal Server Error InternalServerError

Submit an ASR request

1
POST https://api.prosa.ai/v2/speech/stt

Submit an ASR request. For ASR requests on small amounts of audio data i.e. below one minute (this may vary based on configuration), the base64-encoded audio data must be included in the request body. For large amounts of audio data, the publicly accessible URI of the audio file must be provided instead.

Currently supported URI: - http url that returns audio file. e.g.: https://storage/file - url to google drive audio file or google drive file id. e.g.: googledrive://file_id

For short ASR requests, the application processes the job on the fly; the client is expected to wait for the result to be returned in the response. However, if the job cannot be completed in the allotted timeframe, it is instead queued and only the job ID is returned. For long ASR requests, the job is always queued. You can then poll for results. Alternatively, you can set up a webhook endpoint to receive notifications for all running jobs. See Receiving Prosa Webhook.

For multichannel audio files, each channel will be treated as different audio input. Each returned transcription will have the channel tag to specify which audio channel they are from.

Body parameter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "config": {
    "engine": "stt-general",
    "wait": false,
    "speaker_count": 1,
    "include_filler": false,
    "include_partial_results": false,
    "auto_punctuation": false,
    "enable_spoken_numerals": false,
    "enable_speech_insights": false,
    "enable_voice_insights": false
  },
  "request": {
    "label": "Meeting Audio 2021-14-06",
    "data": "<base64 encoded audio>"
  }
}

Parameters

Name In Type Required Description
body body AsrJobRequest true -

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "job_id": "2fec34e1efb146f7a7431cb35b64550d",
  "status": "complete",
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "request": {
    "label": "Meeting Audio 2021-14-06",
    "data": "<base64 encoded audio>"
  },
  "result": {
    "data": [
      {
        "words": "Hasil akhir dari pekerjaan ini cukup memuaskan",
        "final": true,
        "time_start": 0,
        "time_end": 3.6,
        "channel" : 0
      },
      {
        "words": "Hanya saja",
        "final": false,
        "time_start": 0,
        "time_end": 0,
        "channel" : 0
      }
    ]
  },
  "job_config": {
    "model": "stt-general",
    "wait": false,
    "include_filler": false,
    "include_partial_results": false
  },
  "progress": {
    "total": 0,
    "details": {
      "transfer": 0,
      "transcribe": 0
    }
  },
  "model": {
    "name": "string",
    "label": "string",
    "language": "string",
    "domain": "string",
    "acoustic": "string",
    "channels": 0,
    "samplerate": 0
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response AsrResponse
400 Bad Request Bad Request
401 Unauthorized Unauthorized
403 Forbidden Forbidden ForbiddenError
422 Unprocessable Entity Validation Error RequestValidationError
500 Internal Server Error Internal Server Error InternalServerError

Alternative Audio Source

Each request is limited to 10 MB in size. This indirectly limits the audio duration that can be submitted via base64-encoded string. Alternatively, a request can be made using url to external storage.

Example request

1
2
3
4
5
6
7
8
{
    "config": {
        "model": "stt-general"
    },
    "request": {
        "uri": "googledrive://1p2mVUsalFLKdSvuEcu4eCoWzYqi4lzk5"
    }
}

Important

URI-based requests are only allowed for asynchronous requests.

Supported External Storage

Here are the list of currently supported external storage.

External Storage Protocol Prefix Description Example
Arbitrary Storage https:// The file must be located on a publicly accessible url. https://example.com/media/example_audio.wav
Google Drive googledrive:// Protocol prefix followed by file_id. The file must be publicly accessible. googledrive://1p2mVUsalFLKdSvuEcu4eCoWzYqi4lzk5

Receive Prosa Webhook

You can register a webhook to receive notification about the running of ASR jobs. Webhook events are emitted on job completion or job error.

Note

For more details webhook usage, see Prosa Webhook.

Body parameter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "job_id": "063c64da-180d-731e-8000-d11a28529080",
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "request": {
    "uri": "https://example.domain.name/media/example_audio.wav",
    "label": "Example audio",
    "channels": 1,
    "duration": 6.766625,
    "mime_type": "audio/wav",
    "sample_rate": 8000
  },
  "job_config": {
    "wait": false,
    "engine": "stt-general",
    "speaker_count": 1,
    "include_filler": false,
    "include_partial_results": false
  },
  "model": {
    "name": "stt-general",
    "label": "ASR General",
    "domain": "general",
    "acoustic": "recording",
    "channels": 1,
    "language": "Bahasa Indonesia",
    "samplerate": 16000
  },
  "result": {
    "data": [
      {
        "transcript": "Hasil akhir dari pekerjaan ini cukup memuaskan",
        "final": true,
        "time_start": 0,
        "time_end": 3.6,
        "channel": 0,
        "speaker_tag": 1
      },
      {
        "transcript": "Hanya saja",
        "final": false,
        "time_start": 0,
        "time_end": 0,
        "channel": 0,
        "speaker_tag": 1
      }
    ]
  }
}

Parameters

Name In Type Required Description
X-Prosa-Signature header string true -
X-Prosa-Event-UUID header string true -
X-Prosa-Event header string true -
body body any true -

Example responses

400 Response

1
"Invalid signature"

Responses

Status Meaning Description Schema
204 No Content Returned if the webhook processing was successful. None
400 Bad Request Returned if an error occurred while processing webhook event. None
422 Unprocessable Entity Validation Error None

Retrieve an ASR job

1
GET https://api.prosa.ai/v2/speech/stt/{job_id}

Retrieve a specific ASR job.

Parameters

Name In Type Required Description
job_id path string(uuid) true Unique identifier of the job

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "job_id": "2fec34e1efb146f7a7431cb35b64550d",
  "status": "complete",
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "request": {
    "label": "Meeting Audio 2021-14-06",
    "data": "<base64 encoded audio>"
  },
  "result": {
    "data": [
      {
        "transcript": "Hasil akhir dari pekerjaan ini cukup memuaskan",
        "final": true,
        "time_start": 0,
        "time_end": 3.6,
        "channel": 0
      },
      {
        "transcript": "Hanya saja",
        "final": false,
        "time_start": 0,
        "time_end": 0,
        "channel": 0
      }
    ]
  },
  "job_config": {
    "model": "stt-general",
    "wait": false,
    "include_filler": false,
    "include_partial_results": false
  },
  "progress": {
    "total": 0,
    "details": {
      "transfer": 0,
      "transcribe": 0
    }
  },
  "model": {
    "name": "string",
    "label": "string",
    "language": "string",
    "domain": "string",
    "acoustic": "string",
    "channels": 0,
    "samplerate": 0
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response AsrResponse
401 Unauthorized Unauthorized
403 Forbidden Forbidden ForbiddenError
404 Not Found Not Found JobNotFoundError
422 Unprocessable Entity Validation Error RequestValidationError
500 Internal Server Error Internal Server Error InternalServerError

Archive an ASR job

1
DELETE https://api.prosa.ai/v2/speech/stt/{job_id}

Archive an ASR job. Archived jobs are soft-deleted rather than deleted from the database entirely. Hence, job details and results are still stored. The behavior differs based on the job status:

  • HTTP 404 is returned if the job is not found or is already archived.
  • HTTP 404 is returned if the given ID does not belong to the user.
  • HTTP 403 is returned if the job is currently in progress. Archiving jobs in progress is problematic because the underlying job cannot be cancelled, as the compute resources have already been expended. This behavior may change in the future.
  • If the job has completed, the job is soft-deleted and the job details returned.
  • If the job is currently queued or deferred, the job is first cancelled before being soft-deleted, and details returned. No quota is subtracted in this case.

Parameters

Name In Type Required Description
job_id path string(uuid) true -

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "job_id": "2fec34e1efb146f7a7431cb35b64550d",
  "status": "complete",
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "request": {
    "label": "Meeting Audio 2021-14-06",
    "data": "<base64 encoded audio>"
  },
  "result": {
    "data": [
      {
        "transcript": "Hasil akhir dari pekerjaan ini cukup memuaskan",
        "final": true,
        "time_start": 0,
        "time_end": 3.6
      },
      {
        "transcript": "Hanya saja",
        "final": false,
        "time_start": 0,
        "time_end": 0
      }
    ]
  },
  "job_config": {
    "model": "stt-general",
    "wait": false,
    "include_filler": false,
    "include_partial_results": false
  },
  "progress": {
    "total": 0,
    "details": {
      "transfer": 0,
      "transcribe": 0
    }
  },
  "model": {
    "name": "string",
    "label": "string",
    "language": "string",
    "domain": "string",
    "acoustic": "string",
    "channels": 0,
    "samplerate": 0
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response AsrResponse
401 Unauthorized Unauthorized
403 Forbidden Forbidden JobCancellationError
404 Not Found Not Found JobNotFoundError
422 Unprocessable Entity Validation Error RequestValidationError
500 Internal Server Error Internal Server Error InternalServerError

Retrieve an ASR job status

1
GET https://api.prosa.ai/v2/speech/stt/{job_id}/status

Parameters

Name In Type Required Description
job_id path string(uuid) true -

Example responses

200 Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "job_id": "2fec34e1efb146f7a7431cb35b64550d",
  "status": "complete",
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "progress": {
    "total": 0,
    "details": {
      "transfer": 0,
      "transcribe": 0
    }
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response AsrStatusResponse
401 Unauthorized Unauthorized
403 Forbidden Forbidden ForbiddenError
404 Not Found Not Found JobNotFoundError
422 Unprocessable Entity Validation Error RequestValidationError
500 Internal Server Error Internal Server Error InternalServerError