---
title: "Hear a voice"
method: POST
path: "/voices/preview"
tags: ["voices"]
---

# Hear a voice

`POST /voices/preview`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/voices/preview`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Synthesise a short sentence in one of the catalogue's voices and answer a short-lived link to the audio. Send your own `text` (up to 300 characters) or omit it for a stock sentence. The same sentence in the same voice is only ever synthesised once, so repeating a preview is free and instant. When somebody else is synthesising this exact preview at this moment the answer is `status: "preview_pending"` with no URL — ask again in a second.

## Request body

- object
  - `text` string: The sentence to speak. Omit for a stock one.
  - `voiceId` string, required: A voice id from catalog.voices.list.

## Response `200`

Hear a voice

- object
  - `cached` boolean, required: True when the audio already existed and nothing was synthesised.
  - `expiresAt` string, date-time, nullable, required
  - `status` 'ready' | 'preview_pending', required
  - `url` string, nullable, required: A signed link to the audio. Null while the preview is still being made.

## Other responses

- `400`: `validation_failed` — That request is not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.
- `502`: `preview_failed` — That preview could not be made. Try again shortly.
- `503`: `storage_unavailable` — File storage is temporarily unavailable. · `tts_unavailable` — Voice previews are temporarily unavailable.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)