API reference

Voice creation recovery API

Read the recorded result of a voice creation request without starting another creation.

BetaUpdated October 25, 2026

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

Read a voice creation result

GET/ai-voices/request-status

Scope voices:writeRetry with the same Idempotency-Key

Send the same Idempotency-Key used for the original voice creation. Completed returns its saved voice identifier, which must still be checked for availability. Pending means a completion result has not been recorded. Unknown means the result cannot be recovered with this key, including after its 24-hour retention expires. Pending and unknown do not mean that creation did nothing and do not permit a second creation. This read does not create, retry, cancel, or delete a voice.

Headers

Idempotency-Keystringrequired8–128 charspattern ^[\x21-\x7E]{8,128}$
The original creation key; 8-128 visible ASCII characters.

Response 200

Minimal original creation state. No stored request or response body is exposed. Fields below are inside data.

One of 3 shapes:

Option 1

schema_versionintegerrequired
One of1
statusstringrequired
One ofcompleted
voice_idstringrequireduuid

Option 2

schema_versionintegerrequired
One of1
statusstringrequired
One ofpending

Option 3

schema_versionintegerrequired
One of1
statusstringrequired
One ofunknown

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

curl "https://lyricwinter.com/api/v1/ai-voices/request-status" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

import os, uuid
import requests

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

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "status": "completed",
    "voice_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10"
  },
  "request_id": "req_01J9Z3K8QF4"
}