API reference

Voice preparation API

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

BetaUpdated October 4, 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. Signed-in requests also check the requesting account's monthly ElevenLabs allowance: Free 3, MyWinter 20, UltraWinter 60. Each new or renewed ElevenLabs cache addition counts; reuse of a cached voice 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. Already prepared voices can still be used when preparation is exhausted. This check is read-only, does not reserve allowance, and may become stale. Standard Generate may fall back to another engine for an unprepared voice; Studio requires choosing an available engine or waiting for preparation access to return.

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