Speech with word timings (read-along)

POST

/api/v1/audio/speech

text up to 1,500 characters, or one ~1,400-character chunk of a document from offset. A documentId also needs documents:read.

App integration: Decode base64 audio and align words by their UTF-16 start/end offsets; times are seconds within the chunk. Explicit text is at most 1,500 characters; document chunks are about 1,400. Continue at nextOffset until null. A documentId also requires documents:read.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://handwrites.io/oauth/authorize

Token URL: https://handwrites.io/api/oauth/token

Refresh URL: https://handwrites.io/api/oauth/token

Scopes:

audio:read-Stream and fetch spoken audio (uses your monthly characters)

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Base64 audio and word timings.

Headers

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠403Forbidden

🟠404NotFound

🟠429TooManyRequests

🔴500ServerError

🔴502BadGateway

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/audio/speech' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "text": "string",
    "documentId": "string",
    "voice": "string",
    "format": "mp3",
    "model": "string",
    "language": "en",
    "offset": 0
}'

Response Example

200 - Example 1

{
    "audio": "string",
    "format": "mp3",
    "characters": 0,
    "offset": 0,
    "nextOffset": 0,
    "words": [
        {
            "word": "string",
            "start": 0,
            "end": 0,
            "startTime": 0,
            "endTime": 0
        }
    ]
}

Modified at 2026-10-26 12:58:15

Stream speech as it's made

Voices you can use