Start a Real-time STT agent
Updated
Starts subtitle recording and translation.
https://api.agora.io/api/speech-to-text/v1/projects/{appid}/joinUse this method to start subtitle recording and subtitle translation.
Path Parameters
The App ID of the project.
Request Body
application/json
The transcription languages you want to recognize. You can specify up to four languages. For a complete list, see Supported languages. Choosing multiple transcription languages can affect both quality and cost. For best practices, see Optimize transcription quality and cost.
Configure the transcription language for the specified user ID. Supports up to 5 configuration items.
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.
30Range[5, 2592000]Real-time subtitle configuration. After a user's voice is converted to text, the information is pushed to the channel as subtitles to match the UI real-time display.
Subtitle translation configuration.
Subtitle recording configuration.
Optional third-party cloud storage extension configuration. When storage.vendor is set to 11, use this field to specify access information for standard S3-compatible object storage.
Keyword list. Use it to improve the recognition accuracy of specific words during transcription. Supports up to 500 words.
Unique ID of the agent. Maximum length is 64 characters. You cannot use the same ID repeatedly.
Response
- If the returned status code is
200, the request was successful. The response body contains the result of the request.
Response Body
application/json
application/json
Response schema
200application/jsonOK
The ID of the agent.
The Unix timestamp (in seconds) when the agent was created.
The current status of the agent:
IDLE: The agent is not initializedSTARTING: The agent is startingRUNNING: The agent is runningSTOPPING: The agent is exitingSTOPPED: The agent exited successfullyRECOVERING: The agent is recoveringFAILED: Agent exit failed
IDLE | STARTING | RUNNING | STOPPING | STOPPED | RECOVERING | FAILEDResponse
Refer to the detail and reason fields to understand the possible reasons for failure.
Request examples
curl --request POST \ --url https://api.agora.io/api/speech-to-text/v1/projects/:appid/join \ --header 'Authorization: Basic <credentials>' \ --data '{ "languages": [ "en-US" ], "keywords": [ "Agora", "STT" ], "name": "agora-test", "maxIdleTime": 50, "rtcConfig": { "channelName": "agora-test", "pubBotUid": "88222" }, "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 } }}'Response example
{ "agent_id": "Agent ID.", "create_ts": null, "status": "RUNNING"}{ "detail": "Details of the request failure.", "reason": "The reason why the request failed."}