curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Text to speech
Get generated speech
Get an owned speech creation, including its script, delivery settings, temporary audio URL, and available word alignment.
POST
/
v1
/
actions
/
tts_get
curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Get an owned speech creation, including its script, delivery settings, temporary audio URL, and available word alignment.
Required permissions:
POST https://api.voicecheap.ai/v1/actions/tts_get
Authentication and permissions
string
required
Send a VoiceCheap API key in this header. Authorization: Bearer with the same API key is also supported. OAuth access tokens are accepted only by
MCP, not by this REST endpoint.
tts:read.
An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.
Parameters
string
required
History ID returned by tts_generate or tts_list.Pattern:
^(free-)?[0-9a-f]{64}$.Complete input schema
Complete input schema
The JSON Schema below preserves the exact field names, nested types, defaults, bounds, and accepted values exposed by discovery. Additional cross-field rules are listed in the operation notes.
{
"type": "object",
"properties": {
"historyId": {
"type": "string",
"pattern": "^(free-)?[0-9a-f]{64}$",
"description": "History ID returned by tts_generate or tts_list."
}
},
"required": ["historyId"],
"additionalProperties": false
}
Request examples
Replace example resource identifiers and media keys with values returned for your account. Keep the request identifier stable when retrying the same mutation.curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Response
A successful first execution returns HTTP 200 with the operation result under data. A replay may return saved request state instead. The example shows one supported response, not every optional field. Owned speech history detail, full editable and spoken scripts, delivery settings, temporary playback URL, and any available word timestamps.{
"data": {
"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
"text": "Hello world.",
"spokenText": "Hello world.",
"voice": "933563129e564b19a115bedd57b7406a",
"voiceName": "Sarah",
"voiceSource": "catalog",
"inputType": "text",
"instructionPreset": "narrator",
"instructions": "Speak clearly and leave a short pause at the end.",
"speed": 1,
"sourceFileName": "launch-script.txt",
"characterCount": 12,
"durationSeconds": 1.5,
"previewEndIndex": null,
"createdAt": 1792152000000,
"updatedAt": 1792152000000,
"status": "success",
"audioUrl": "https://files.example.com/launch-script.mp3",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
Result fields
| Field | Description |
|---|---|
data.historyId | Owned speech history ID: 64 lowercase hexadecimal characters, optionally prefixed with free- for an app preview. |
data.voice | The original TTS selection ID, including clone:<UUID> for a saved custom voice. |
data.voiceName | Optional saved display name of the selected voice. |
data.voiceSource | Optional voice source: catalog or clone. |
data.inputType | Original input type: text or pdf. |
data.instructionPreset | Stored delivery preset. |
data.sourceFileName | Optional original filename supplied at generation. |
data.characterCount | Character count recorded for this speech creation. |
data.durationSeconds | Audio duration in seconds. |
data.createdAt | Creation time as a Unix timestamp in milliseconds. |
data.updatedAt | Last update time as a Unix timestamp in milliseconds. |
data.status | Stored successful speech items use success; tts_generate uses completed in its generation result. |
data.text | Full editable stored script, including supported delivery control tags. |
data.spokenText | Stored script with supported delivery control tags removed. |
data.instructions | Stored custom delivery instructions; empty when absent. |
data.speed | Stored playback delivery speed; 1 when absent on older records. |
data.previewEndIndex | Character boundary of the available preview, or null for complete audio. |
data.audioUrl | Temporary playable audio URL. |
data.wordAlignment | Word timestamps or null when no alignment is available. |
data.wordAlignment[].text | Aligned word text. |
data.wordAlignment[].startSeconds | Word start time in seconds. |
data.wordAlignment[].endSeconds | Word end time in seconds. |
data.wordAlignment[].sourceStartCharacterIndex | Start character index in spokenText, after delivery control tags have been removed. |
data.wordAlignment[].sourceEndCharacterIndex | End character index in spokenText, after delivery control tags have been removed. |
Operation notes
- historyId must be 64 lowercase hexadecimal characters, optionally prefixed with free-. Use the identifier returned by tts_generate or tts_list.
- Optional older-record properties such as voiceName, voiceSource, and sourceFileName can be omitted. Missing instructions defaults to an empty string, missing speed to 1, and missing previewEndIndex to null.
- wordAlignment can be null. This read loads existing alignment; use tts_align to prepare timestamps.
- Source character indices in wordAlignment refer to spokenText, which has delivery control tags removed.
- audioUrl is temporary. Call tts_get again for fresh playback or tts_download for a download link.
- Speech history and custom voices belong to the authenticated account. Team billing does not grant access to another member’s speech or voices.
Usage
Each successful invocation consumes one monthly API/MCP call. Media credits and the operation’s own generation allowances also apply.Errors
| HTTP status | Code | Meaning or recovery |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | Credentials were supplied in an access_token or api_key query parameter. Send credentials in headers. |
| 400 | VALIDATION_ERROR | The input does not match the action schema; inspect details for field errors. |
| 401 | API_KEY_EXPIRED | The API key has expired. |
| 401 | INVALID_API_KEY | Provide a valid, unexpired API key. |
| 401 | INVALID_CREDENTIAL | The Authorization header is malformed or conflicts with x-api-key. |
| 401 | MISSING_CREDENTIAL | No usable header credential was supplied, or it exceeded 4096 characters. |
| 401 | USER_NOT_FOUND | The credential’s account no longer exists. |
| 403 | AMBIGUOUS_TEAM_API_KEY | The credential’s user belongs to more than one team, so the billing context is ambiguous. |
| 403 | INSUFFICIENT_SCOPE | Grant every required permission or choose another credential. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | The account’s integration limits could not be verified. |
| 403 | SUBSCRIPTION_REQUIRED | Use an active paid subscription. |
| 403 | TEAM_OWNER_NOT_FOUND | The effective team owner account could not be found. |
| 404 | TEXT_TO_SPEECH_HISTORY_NOT_FOUND | The speech history item does not exist or belongs to another account. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Wait for the monthly reset or change plan. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Wait for Retry-After when present and use backoff. |
| 500 | INTERNAL_ERROR | Check saved request state and resource history before deciding to retry a mutation. |
| 503 | SERVER_RESTARTING | The server is restarting. Retry shortly and keep the same request identifier for a mutation. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["tts:read"]
}
}
Was this page helpful?

