# Start a Real-time STT task (/en/api-reference/api-ref/speech-to-text/rest-api-v6/start)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
Real-Time STT API versions v5.x and v6.x are deprecated since June 2025 and will reach end-of-life on June 11, 2026. Use the v7 REST API for new projects.
## Endpoint [#endpoint]
* Method: `POST`
* Endpoint: `https://api.agora.io/v1/projects/{appId}/rtsc/speech-to-text/tasks`
After you [`acquire`](acquire) a `builderToken`, call this method within 5 minutes to start speech-to-text conversion.
## Request [#request]
### Path parameters [#path-parameters]
**`appId`** Type: `string` Required
The App ID of the project
### Query parameters [#query-parameters]
**`builderToken`** Type: `string` Required
The `tokenName` value you obtained in the response body of the [`acquire`](acquire) method. To stop a task, use the same `builderToken` you used to start the task.
### Request body [#request-body]
`APPLICATION/JSON`
#### BODY [#body]
**`languages`** Type: `array[string]` Required
The transcription languages to recognize. You can specify a maximum of 4 languages. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages) for details.
**`uidLanguagesConfig`** Type: `object` Optional
Configure the transcription language for the specified user ID. Supports up to 5 configuration items.
**`uid`** Type: `string` Required
The ID of the user to be transcribed.
**`languages`** Type: `string` Required
You can specify up to 4 languages. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages) for details.
**`maxIdleTime`** Type: `integer` Optional Default: `30` Values: `5 to 2592000`
Maximum channel idle time, in seconds. When the specified time is exceeded, the transcription task ends automatically. Idle time means that there is no host in a live broadcast channel, or there is no user in a communication channel.
**`rtcConfig`** Type: `object` Required
**`channelName`** Type: `string` Required
The name of the channel to transcribe.
**`subBotUid`** Type: `string` Required
The ID of the bot that subscribes to the audio stream. All UIDs within a channel must be unique. Ensure no other user or service bot is using this UID in the same channel.
**`subBotToken`** Type: `string` Optional
The token used by the subscribing bot for channel authentication. Required only when your project has [App Certificate](/en/realtime-media/video/reference/core-concepts#app-certificate) enabled. Generate this token on your token server. For details, see [Token authentication](/en/realtime-media/video/build/authenticate-users/deploy-token-server).
**`pubBotUid`** Type: `string` Required
The ID of the bot that pushes subtitle information to the channel. All UIDs within a channel must be unique. Ensure no other user or service bot is using this UID in the same channel.
**`pubBotToken`** Type: `string` Optional
The token used by the subtitle-pushing bot for channel authentication. Required only when your project has [App Certificate](/en/realtime-media/video/reference/core-concepts#app-certificate) enabled. Generate this token on your token server. For details, see [Token authentication](/en/realtime-media/video/build/authenticate-users/deploy-token-server).
**`subscribeAudioUids`** Type: `array[string]` Optional
The user IDs of the audio streams you want to subscribe to. Specify this parameter only if you need to subscribe to specific users. Maximum array length: 3.
**`cryptionMode`** Type: `integer` Optional Values: `0 to 8`
The encryption and decryption mode. When enabled, this mode is used for both decrypting incoming streams and encrypting outgoing subtitles.
* `0`: No encryption
* `1`: `AES_128_XTS` 128-bit AES encryption, XTS mode
* `2`: `AES_128_ECB` 128-bit AES encryption, ECB mode
* `3`: `AES_256_XTS` 256-bit AES encryption, XTS mode
* `4`: `SM4_128_ECB` 128-bit SM4 encryption, ECB mode
* `5`: `AES_128_GCM` 128-bit AES encryption, GCM mode
* `6`: `AES_256_GCM` 256-bit AES encryption, GCM mode
* `7`: `AES_128_GCM2` 128-bit AES encryption, GCM mode, Compared with `AES_128_GCM` encryption mode, this encryption mode is more secure and requires setting a key and salt.
* `8`: `AES_256_GCM2` 256-bit AES encryption, GCM mode, Compared with `AES_256_GCM` encryption mode, this encryption mode is more secure and requires setting a key and salt.
The decryption method must match the encryption method set for the channel.
**`salt`** Type: `string` Optional
A Base64-encoded, 32-byte encryption/decryption salt. Required only when `cryptionMode` is `7` or `8`.
**`secret`** Type: `string` Optional
The encryption/decryption key. Required when `cryptionMode` is not `0`.
**`enableJsonProtocol`** Type: `boolean` Optional Default: `false`
Set the encoding format of the subtitle data pushed to the channel.
* `true`: Use JSON to push subtitles and compress data with gzip. Uses less bandwidth, but requires decoding.
* `false`: Use Protobuf to push subtitles (default). The data volume is smaller. Suitable for scenarios with high transmission efficiency requirements.
**`subscribeAudioUids`** Type: `array[string]` Optional
The user IDs for the audio streams you want to subscribe. To subscribe to audio streams from all users, set this parameter to `["all"]`. Maximum array length: 32. You can set either `subscribeAudioUids` or `unSubscribeAudioUids`.
**`unSubscribeAudioUids`** Type: `array[string]` Optional
The user IDs for the audio streams you **do not want to subscribe**. Maximum array length: 5. You can set either `subscribeAudioUids` or `unSubscribeAudioUids`.
**`translateConfig`** Type: `object` Optional
Subtitle translation configuration.
**`languages`** Type: `array` Required
The translation language array. You can specify a maximum of 4 different source languages. The source language and target language must be different, otherwise an error is reported.\
Each array item is an object with:
**`source`** Type: `string` Required
The source language for translation. Refer to [Supported Languages](/en/realtime-media/speech-to-text/reference/supported-languages) for details.
**`target`** Type: `array[string]` Required
The target languages for translation. You can specify a maximum of 5 target languages for each source language. Refer to [Supported Languages](/real-time-stt/develop/translation#supported-languages) for details.
**`captionConfig`** Type: `object` Optional
Subtitle recording configuration.
**`sliceDuration`** Type: `integer` Optional Default: `60` Values: `5 to 28800`
The slice size of the recorded subtitle file, in seconds.
**`storage`** Type: `object` Required
**`accesskey`** Type: `string` Required
The access key of the third-party cloud storage.
**`secretkey`** Type: `string` Required
The secret key of the third-party cloud storage.
**`bucket`** Type: `string` Required
The bucket name of the third-party cloud storage.
**`vendor`** Type: `integer` Required Values: `1,5,6`
The third-party cloud storage platform:
* `1`: Amazon S3
* `5`: Microsoft Azure
* `6`: Google Cloud
**`region`** Type: `integer` Required
The region information for the third-party cloud storage. To ensure successful and real-time uploading of recorded files, the cloud storage region must match the region of the application server where you initiate the request. For example, if your App server is in East US, set the cloud storage region to East US as well. See [third-party storage regions](/cloud-recording/reference/region-vendor) for details.
**`fileNamePrefix`** Type: `array[string]` Optional
The storage location of the recorded file in the third-party cloud storage. The prefix length (including slashes) must not exceed 128 characters. The following characters are supported:
* Lowercase English letters (a-z)
* Uppercase English letters (A-Z)
* Numbers (0-9)\
Symbols like slashes, underscores, and brackets must not appear in the string.
## Response [#response]
* If the returned status code is `200`, the request was successful. The response body contains the result of the request.
#### OK [#ok]
**`taskId`** Type: `string` Required
The unique identifier of this transcription task.
**`createTs`** Type: `integer` Required
The Unix timestamp (in seconds) when the transcription task was created.
**`status`** Type: `string` Required
The current status of the transcription task:
* `IDLE`: Task not initialized
* `PREPARING`: Task has received an initialization request
* `PREPARED`: Task initialization completed
* `STARTING`: Task is beginning to start
* `CREATED`: Task startup partially completed
* `STARTED`: Task startup fully completed
* `IN_PROGRESS`: Task is currently running
* `STOPPING`: Task is in the process of being paused
* `STOPPED`: Task has been terminated
* `FAILURE_STOP`: Task termination failed
* If the returned status code is not `200`, the request failed. Refer to the `message` field to understand the possible reasons for failure.
#### Non-200 [#non-200]
**`message`** Type: `string`
The reason why the request failed.
## Authorization [#authorization]
This endpoint requires [Basic Auth](../authentication).
## Request example [#request-example]
curl
Python
Node.js
```bash
curl --request POST \
--url 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks?builderToken=your_builder_token' \
--header 'Authorization: Basic ' \
--header 'Content-Type: ' \
--data '
{
"languages": [
"en-US"
],
"maxIdleTime": 50,
"rtcConfig": {
"channelName": "agora-test",
"subBotUid": "47091",
"pubBotUid": "88222",
"subscribeAudioUids": [
"45321",
"23433"
]
},
"translateConfig": {
"languages": [
{
"source": "en-US",
"target": [
"ar-SA",
"id-ID",
"fr-FR",
"ja-JP"
]
}
]
},
"captionConfig": {
"sliceDuration": 60,
"storage": {
"accessKey": "test-oss",
"secretKey": "test-oss",
"bucket": "test-oss",
"vendor": 2,
"region": 3
}
}
}'
```
```python
import requests
url = "https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks?builderToken=your_builder_token"
payload = {
"languages": ["en-US"],
"maxIdleTime": 50,
"rtcConfig": {
"channelName": "agora-test",
"subBotUid": "47091",
"pubBotUid": "88222",
"subscribeAudioUids": ["45321", "23433"]
},
"translateConfig": { "languages": [
{
"source": "en-US",
"target": ["ar-SA", "id-ID", "fr-FR", "ja-JP"]
}
] },
"captionConfig": {
"sliceDuration": 60,
"storage": {
"accessKey": "test-oss",
"secretKey": "test-oss",
"bucket": "test-oss",
"vendor": 2,
"region": 3
}
}
}
headers = {
"Authorization": "Basic ",
"Content-Type": ""
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
```
```js
const url = 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks?builderToken=your_builder_token';
const options = {
method: 'POST',
headers: {Authorization: 'Basic ', 'Content-Type': ''},
body: JSON.stringify({
languages: ['en-US'],
maxIdleTime: 50,
rtcConfig: {
channelName: 'agora-test',
subBotUid: '47091',
pubBotUid: '88222',
subscribeAudioUids: ['45321', '23433']
},
translateConfig: {
languages: [{source: 'en-US', target: ['ar-SA', 'id-ID', 'fr-FR', 'ja-JP']}]
},
captionConfig: {
sliceDuration: 60,
storage: {
accessKey: 'test-oss',
secretKey: 'test-oss',
bucket: 'test-oss',
vendor: 2,
region: 3
}
}
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));
```
## Response example [#response-example]
### 200 [#200]
```json
{
"taskId": "XXXX",
"createTs": 1678505852,
"status": "IN_PROGRESS"
}
```
### Non-200 [#non-200-1]
```json
{
"message": "The reason why the request failed.",
}
```