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

# Obtener voz generada

> Obtén una creación de voz de tu propiedad, con su guion, los ajustes de interpretación, una URL temporal del audio y la alineación de palabras disponible.

Obtén una creación de voz de tu propiedad, con su guion, los ajustes de interpretación, una URL temporal del audio y la alineación de palabras disponible.

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

## Autenticación y permisos

<ParamField header="x-api-key" type="string" required>
  Envía una clave de API de VoiceCheap en esta cabecera. También se admite Authorization: Bearer con la misma clave de API. Los tokens de acceso OAuth
  solo se aceptan en MCP, no en este endpoint REST.
</ParamField>

Permisos necesarios: `tts:read`.

Se requiere una suscripción de pago activa. Los permisos no cambian los roles del equipo, la propiedad de los recursos, los créditos multimedia ni los límites del plan.

## Parámetros

<ParamField body="historyId" type="string" required>
  ID de historial devuelto por tts\_generate o tts\_list.

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

<Accordion title="Esquema completo de entrada">
  El JSON Schema siguiente conserva los nombres exactos de los campos, los tipos anidados, los valores predeterminados, los límites y los valores aceptados que expone el descubrimiento. Las reglas adicionales entre campos se indican en las notas de la operación.

  ```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>

## Ejemplos de solicitud

Sustituye los identificadores de recursos y las claves multimedia de los ejemplos por valores devueltos para tu cuenta. Mantén el identificador de solicitud al reintentar la misma modificación.

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

## Respuesta

Una primera ejecución correcta devuelve HTTP 200 con el resultado de la operación en data. Una repetición puede devolver el estado de la solicitud guardada en su lugar. El ejemplo muestra una respuesta admitida, no todos los campos opcionales.

Detalle del historial de voz que pertenece a la cuenta, guiones completos editable y hablado, ajustes de locución, URL temporal de reproducción y las marcas de tiempo de palabras disponibles.

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

## Campos del resultado

| Campo | Descripción |
| - | - |
| `data.historyId` | ID del historial de voz perteneciente al usuario: 64 caracteres hexadecimales en minúsculas, con el prefijo opcional free- para una vista previa de la aplicación. |
| `data.voice` | El ID de selección TTS original, incluido clone:\<UUID> para una voz personalizada guardada. |
| `data.voiceName` | Nombre visible guardado opcional de la voz seleccionada. |
| `data.voiceSource` | Origen de voz opcional: catalog o clone. |
| `data.inputType` | Tipo de entrada original: text o pdf. |
| `data.instructionPreset` | Preajuste de interpretación almacenado. |
| `data.sourceFileName` | Nombre de archivo original opcional proporcionado durante la generación. |
| `data.characterCount` | Número de caracteres registrado para esta creación de voz. |
| `data.durationSeconds` | Duración del audio en segundos. |
| `data.createdAt` | Hora de creación como marca de tiempo Unix en milisegundos. |
| `data.updatedAt` | Hora de la última actualización como marca de tiempo Unix en milisegundos. |
| `data.status` | Los elementos de voz almacenados correctamente usan success; tts\_generate usa completed en el resultado de su generación. |
| `data.text` | Guion completo almacenado y editable, incluidas las etiquetas de control de interpretación admitidas. |
| `data.spokenText` | Guion almacenado sin las etiquetas de control de interpretación admitidas. |
| `data.instructions` | Instrucciones personalizadas de interpretación almacenadas; están vacías cuando no están presentes. |
| `data.speed` | Velocidad de interpretación almacenada para la reproducción; 1 si no está presente en registros antiguos. |
| `data.previewEndIndex` | Límite de caracteres de la vista previa disponible, o null para el audio completo. |
| `data.audioUrl` | URL temporal reproducible del audio. |
| `data.wordAlignment` | Marcas de tiempo de palabras o null cuando no hay alineación disponible. |
| `data.wordAlignment[].text` | Texto de la palabra alineada. |
| `data.wordAlignment[].startSeconds` | Tiempo de inicio de la palabra en segundos. |
| `data.wordAlignment[].endSeconds` | Hora de finalización de la palabra en segundos. |
| `data.wordAlignment[].sourceStartCharacterIndex` | Índice del carácter inicial en spokenText, una vez eliminadas las etiquetas de control de locución. |
| `data.wordAlignment[].sourceEndCharacterIndex` | Índice del carácter final en spokenText, después de eliminar las etiquetas de control de interpretación. |

## Notas de la operación

* historyId debe tener 64 caracteres hexadecimales en minúsculas, con el prefijo opcional free-. Usa el identificador devuelto por tts\_generate o tts\_list.
* Se pueden omitir propiedades opcionales de registros antiguos, como voiceName, voiceSource y sourceFileName. Si falta instructions, el valor predeterminado es una cadena vacía; si falta speed, es 1; y si falta previewEndIndex, es null.
* wordAlignment puede ser null. Esta consulta carga la alineación existente; usa tts\_align para preparar las marcas de tiempo.
* Los índices de caracteres de origen de wordAlignment hacen referencia a spokenText, del que se han eliminado las etiquetas de control de locución.
* audioUrl es temporal. Vuelve a llamar a tts\_get para renovar la reproducción o a tts\_download para obtener un enlace de descarga.
* El historial de síntesis de voz y las voces personalizadas pertenecen a la cuenta autenticada. La facturación del equipo no concede acceso a las síntesis de voz ni a las voces de otro miembro.

## Uso

Cada invocación correcta consume una llamada mensual de API/MCP. También se aplican los créditos multimedia y las cuotas de generación propias de la operación.

## Errores

| Estado HTTP | Código | Significado o solución |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Se han proporcionado credenciales en un parámetro de consulta access\_token o api\_key. Envía las credenciales en las cabeceras. |
| 400 | `VALIDATION_ERROR` | La entrada no coincide con el esquema de la acción; consulta details para ver los errores de los campos. |
| 401 | `API_KEY_EXPIRED` | La clave API ha caducado. |
| 401 | `INVALID_API_KEY` | Proporciona una clave de API válida que no haya caducado. |
| 401 | `INVALID_CREDENTIAL` | La cabecera Authorization tiene un formato incorrecto o entra en conflicto con x-api-key. |
| 401 | `MISSING_CREDENTIAL` | No se proporcionó ninguna credencial de cabecera utilizable o superaba 4096 caracteres. |
| 401 | `USER_NOT_FOUND` | La cuenta de la credencial ya no existe. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | El usuario de la credencial pertenece a más de un equipo, por lo que el contexto de facturación es ambiguo. |
| 403 | `INSUFFICIENT_SCOPE` | Concede todos los permisos necesarios o elige otra credencial. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | No se han podido verificar los límites de integración de la cuenta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Usa una suscripción de pago activa. |
| 403 | `TEAM_OWNER_NOT_FOUND` | No se pudo encontrar la cuenta del propietario efectivo del equipo. |
| 404 | `TEXT_TO_SPEECH_HISTORY_NOT_FOUND` | El elemento del historial de voz no existe o pertenece a otra cuenta. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Espera al restablecimiento mensual o cambia de plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Espera el tiempo indicado en Retry-After cuando esté presente y aplica esperas progresivas. |
| 500 | `INTERNAL_ERROR` | Comprueba el estado de la solicitud guardada y el historial del recurso antes de decidir si reintentas una modificación. |
| 503 | `SERVER_RESTARTING` | El servidor se está reiniciando. Reinténtalo en breve y conserva el mismo identificador de solicitud para una modificación. |

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