> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get generated speech

> Get an owned speech creation, including its script, delivery settings, temporary audio URL, and available word alignment.

Get an owned speech creation, including its script, delivery settings, temporary audio URL, and available word alignment.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/tts_get
```

## Authentication and permissions

<ParamField header="x-api-key" type="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.
</ParamField>

Required permissions: `tts:read`.

An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.

## Parameters

<ParamField body="historyId" type="string" required>
  History ID returned by tts\_generate or tts\_list.

  Pattern: `^(free-)?[0-9a-f]{64}$`.
</ParamField>

<Accordion title="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.

  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

## 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.

<RequestExample>
  ```bash cURL theme={null}
  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"}'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</RequestExample>

## 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.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "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
        }
      ]
    }
  }
  ```
</ResponseExample>

## 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. |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["tts:read"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.