Acquire a builder token

info

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. This affects your projects as follows:

• New projects: Projects you create starting June 2025 must use v7.0.
• Existing projects: If you're using v5.x or v6.x, migrate to v7.0 before June 11, 2026 to avoid service interruption.

Acquire a builder token

POST

https://api.agora.io/v1/projects/{appId}/rtsc/speech-to-text/builderTokens

Before starting Real-Time STT conversion, call this endpoint to obtain a builderToken. The validity period of a builderToken is 5 minutes. After acquiring a token, call the start method within the token validity period to start a Real-Time STT task.

appId stringrequired

The App ID of the project

APPLICATION/JSON

BODYrequired

• instanceId stringrequired

  User-defined string identifier. Must be no more than 64 characters and can include:

  • All lowercase English letters (a-z)
  • All capital letters (A-Z)
  • Numbers 0-9
  • -, _

  You can generate multiple builder tokens using an instanceId, but only one token can be used to initiate a task.

• If the returned status code is 200, the request was successful. The response body contains the result of the request.

  OK

  • createTs integer

    Unix timestamp (seconds) when the builderToken was generated.

  • instanceId string

    The instanceId you specified in the request.

  • tokenName string

    The value of the builderToken you use to call other methods.

• If the returned status code is not 200, the request failed. Refer to message field to understand the possible reasons for failure.

  Non-200

  • message string

    The reason why the request failed.

Authorization

This endpoint requires Basic Auth.

Request example

• curl
• Python
• Node.js

_8

curl --request POST \

_8

--url https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/builderTokens \

_8

--header 'Authorization: Basic <credentials>' \

_8

--header 'Content-Type: <string>' \

_8

--data '

_8

{

_8

"instanceId": "User-defined instance ID"

_8

}'

Response example

• 200
• Non-200

_5

{

_5

"createTs": 1678505791,

_5

"instanceId": "XXXX",

_5

"tokenName": "tokenName of the transcription task"

_5

}