API reference

Voice preparation API

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.

BetaUpdated October 15, 2026

Markdown Ask ChatGPT Ask Claude

Base URL: https://lyricwinter.com/api/v1
Authentication: Authorization: Bearer lw_…
Contract: openapi.json

Check voice preparation readiness

GET/voices/preparation-status

Scope voices:read

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

voice_idsstring
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 below are inside data.

provider"elevenlabs"required
statusstringrequired
One ofavailableexhaustedunknown
noticestring | nullrequired
voicesarray of objectrequired
2 item attributes
- voice_idstringrequireduuid
- preparation_requiredbooleanrequired

Errors 400, 401, 403, 500 use the standard error envelope.

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

const response = await fetch(`https://lyricwinter.com/api/v1/voices/preparation-status`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/voices/preparation-status",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "provider": "elevenlabs",
    "status": "available",
    "notice": "string",
    "voices": [
      {
        "voice_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "preparation_required": true
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}