---
title: "Voice creation recovery API"
description: "Read the recorded result of a voice creation request without starting another creation."
canonical_url: https://lyricwinter.com/docs/api/voice-creation-recovery
markdown_url: https://lyricwinter.com/docs/api/voice-creation-recovery.md
last_updated: 2026-10-25
status: beta
---
# LyricWinter API reference: Voice creation recovery

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

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

- [Read a voice creation result](https://lyricwinter.com/docs/api/voice-creation-recovery#get-ai-voice-request-status): `GET /ai-voices/request-status`

### Read a voice creation result

`GET /ai-voices/request-status`

Scope: `voices:write` · Retries: send an `Idempotency-Key` header · Operation ID: `getAiVoiceRequestStatus`

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string, 8–128 chars, pattern ^[\x21-\x7E]{8,128}$ | Yes | The original creation key; 8-128 visible ASCII characters. |

#### Response 200

Minimal original creation state. No stored request or response body is exposed.

Fields inside `data`:

- One of:
  - **Option 1**
    - `schema_version` (integer, one of `1`; required)
    - `status` (string, one of `completed`; required)
    - `voice_id` (string, uuid; required)
  - **Option 2**
    - `schema_version` (integer, one of `1`; required)
    - `status` (string, one of `pending`; required)
  - **Option 3**
    - `schema_version` (integer, one of `1`; required)
    - `status` (string, one of `unknown`; required)

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

#### Example request

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