---
title: "Voice preparation API"
description: "Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. ElevenLabs v4 requires a paid plan. This read-only check does not create voices or reserve provider allowance."
canonical_url: https://lyricwinter.com/docs/api/voice-preparation
markdown_url: https://lyricwinter.com/docs/api/voice-preparation.md
last_updated: 2026-10-15
status: beta
---
# LyricWinter API reference: Voice preparation

> Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. ElevenLabs v4 requires a paid plan. This read-only check does not create voices or reserve provider allowance.

The LyricWinter API is in beta. Base URL: `https://lyricwinter.com/api/v1`. Authenticate every request with `Authorization: Bearer lw_...`. Successful responses are wrapped as `{ "data": ..., "request_id": "req_..." }`. Machine-readable contract: https://lyricwinter.com/api/v1/openapi.json.

## Endpoints

- [Check voice preparation readiness](https://lyricwinter.com/docs/api/voice-preparation#get-voice-preparation-status): `GET /voices/preparation-status`

### Check voice preparation readiness

`GET /voices/preparation-status`

Scope: `voices:read` · Operation ID: `getVoicePreparationStatus`

Check current ElevenLabs preparation availability and whether each accessible voice already has a prepared current-revision voice. ElevenLabs v4 requires an active paid plan, including when the voice is already prepared. Signed-in requests also check the requesting account's monthly custom voice clone allowance: MyWinter 20, UltraWinter 60; free accounts have no allowance. Each new or renewed clone counts; reuse of a current clone and other engines do not. Allowances reset on the first of each month at 00:00 UTC, including annual subscriptions. Anonymous requests check provider availability only. Pass up to 50 comma-separated UUIDs in voice_ids, or omit them for a new voice. The response status is available, exhausted, or unknown; the notice distinguishes an account limit from shared provider exhaustion. Paid accounts can still use prepared voices when cloning is unavailable. This check is read-only, does not reserve allowance, and may become stale. Free accounts must choose another engine; existing audio remains playable.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `voice_ids` | string | No | Up to 50 comma-separated UUIDs. Omit to check new voice preparation without selecting existing voices. |

#### Response 200

Current provider preparation state and cache readiness for accessible voices only.

Fields inside `data`:

- `provider` ("elevenlabs"; required)
- `status` (string, one of `available`, `exhausted`, `unknown`; required)
- `notice` (string | null; required)
- `voices` (array of object; required)
  - `voice_id` (string, uuid; required)
  - `preparation_required` (boolean; required)

Errors: `400`, `401`, `403`, `500` return the standard error envelope.

#### Example request

```bash
curl "https://lyricwinter.com/api/v1/voices/preparation-status" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"
```