API Reference

Overview

The Lazybird Speech API lets you list available voices, generate MP3 speech from text or SSML, and create, edit and publish cloned voices.

Base URL:

/v1 keeps working for existing integrations. It differs only in GET /voices, which there returns one unpaged list of the first 1,000 library voices (?owner=me for your own).

A machine-readable OpenAPI 3.1 description of every endpoint is at www.lazybird.app/openapi.json.

Authentication

There are two ways to get an API key:

• Create one in your Lazybird Studio settings.
• Request one by email, without opening the studio. This is built for AI agents; see Get an API key without the UI.

Send the key with each request.

Preferred header:

You can also pass the key as an api_key query parameter when a tool cannot set headers:

Keep API keys private. Do not expose them in browser code, mobile apps, public repositories, or client-side logs.

Get an API key without the UI (for agents)

An agent can sign up or log in with just an email address. Lazybird emails a 6-digit code; the agent (or you, reading the code back to it) trades the code for a new API key. If no account exists for the email, a free account is created.

1. Request a code

Response (202 Accepted):

The response is the same whether or not an account exists for the email. Use a permanent inbox; disposable email domains are rejected with 400. You can request one code per email per minute and five per hour; extra requests get 429 with a Retry-After header.

2. Verify the code

Response:

Codes expire after 10 minutes and work once. A wrong or expired code returns 400 with {"error": "Invalid or expired code"}; after five wrong attempts the code is cancelled and you need to request a new one. Repeated wrong codes for one email, or too many attempts or new accounts from one network or one email domain, return 429 with a Retry-After header. Company and custom domains can create up to 15 new accounts a day this way. A 429 for too many new accounts leaves the code valid, so you can retry before it expires. Each successful verification creates a new key; existing keys keep working.

Store the key somewhere private, such as an environment variable. Accounts created this way start on the free plan; see Check your account and Upgrade your plan.

Agent skill

When you are using an AI coding agent, install the official Lazybird API skill so the agent has the current API shape, examples, and integration gotchas available in context.

Quickstart

Generate speech with a known voice ID:

The response is an MP3 audio file. Save the response body to a file instead of trying to display it as JSON.

Check service status

Returns the current API health.

Example:

Response:

Check your account

Returns the account the API key belongs to, its plan and credit usage for the current period.

Response:

plan.tier is one of free, creator, pro, max, or legacy for older plans. remaining is the plan allowance left this period plus any purchased extraCredits. resetsAt is when used goes back to zero; it is omitted for team seats. One credit is one character. The plan allowance is used first; purchased extraCredits never expire.

Upgrade or buy credits

Creates a checkout link for a paid plan, or for a one-time pack of extra credits. Open the link in a browser to pay; the plan or credits apply to the account as soon as payment completes, and the same API key keeps working.

Extra credits cost $30 per 1M with no plan, $20 per 1M on Creator and $5 per 1M on Pro or Max, so {"creditsUsd":10} buys 333,333 credits with no plan or 2,000,000 on Pro. They never expire. Without a plan they are for personal use; plans include commercial rights.

Response:

See pricing for what each plan includes.

List voices

Returns the voices you can use with generate-speech, in two sections:

• myVoices: your own voices (your clones, and any you have published)
• library: the public voice library

Example:

Query parameters (all optional):

Response (abbreviated):

totals is the number of matching voices in each section. Use the id value as voiceId when generating speech.

Page through a section

Add section to get one section, limit voices at a time. While more voices match, the response includes nextCursor; send it back as cursor with the same filters and sort to get the next page.

The last page has no nextCursor. If the voice a cursor points at is removed, the request fails with 400; start again from the first page.

Generate speech

Generates speech with the selected voice and returns an MP3 audio file.

Headers:

Body:

Provide either text or ssml.

Plain text example

SSML example

Voice settings example

All settings fields are optional.

Settings:

Locale override

Use settings.locale to choose the spoken language or accent for multilingual voices. This is especially important for cloned voices, which can be synthesized in different languages by passing a locale override.

List your voices

Returns only your own voices: private cloned voices and any you have published, paged like the library (limit, cursor).

Example:

Response (abbreviated):

Use the id as voiceId when generating speech. Treat it as opaque. Voices cloned before the unified voice list also accept their legacy pv: id anywhere a voice ID is accepted.

Create a voice

Creates a private cloned voice from a voice sample. Voice cloning requires a plan with voice cloning access and available voice slots.

Upload the sample file as multipart/form-data:

If the sample is already hosted at a publicly reachable URL, send JSON instead:

Send either a sample file or a sampleUrl, not both. A successful request returns 201 Created with the new voice:

Design a voice

Generates a new voice from a text description of who is speaking and returns a sample of it speaking text. The description is never spoken. Requires voice cloning access.

Designing does not create a voice or use a voice slot. To keep a design, pass its sampleUrl to Create a voice:

Generate speech with a cloned voice

Cloned voices work with the normal speech endpoint. Pass the voice id as voiceId:

Get a voice

Returns one voice: any voice in the public library, or one of your own private voices.

Response:

Update a voice

Changes the details of one of your own voices. Send only the fields you want to change. Edits to a published voice show in the public library right away.

To upload the avatar image from a file instead, send multipart/form-data with the image as avatar (PNG, JPEG or WebP, up to 5 MB). The other fields can go in the same form; send labels comma-separated:

Avatars are cropped to a 200×200 square, so use a square image with the face centred. Send either an avatar file or an avatarUrl, not both. Unknown fields are rejected with 400.

The response is the updated voice, in the same { "voice": { ... } } shape as Get a voice. Changing language clears the voice's preview clip, because the preview line follows the language; render it again afterwards.

Replace a voice sample

Clones one of your voices again from a new recording. The voice keeps its ID, name, description, labels, language and avatar, so existing projects and integrations keep working and speak with the new sample from then on. Use it when the original sample had background noise, music or a second speaker.

Upload the new sample as multipart/form-data:

Or send JSON with a publicly reachable sampleUrl instead of the file:

Replacing a sample counts as one voice creation toward your plan's monthly limit, but does not use another voice slot. A published voice changes for everyone who uses it, so rightsConfirmed is required for those. The response is the updated voice, in the same { "voice": { ... } } shape as Get a voice. The old preview clip is cleared; render it again afterwards.

Publish a voice

Adds one of your private voices to the public voice library. Anyone can then find it, open its page at https://lazybird.app/voices/{voiceId} and generate speech with it. Give the voice a name, description, labels, language and avatar before publishing; they are what people see in the library.

The response is the voice, now with "scope": "community" and "published": true.

To take it out of the library again, use POST /voices/{voiceId}/unpublish. The voice stays in your own voices.

Render a voice preview

Returns the voice's short preview clip, the previewText line spoken in the voice. The first call renders it; later calls return the stored clip. Rendering is charged to the voice owner's credits.

Response:

duration is in seconds and is only included when this call rendered the clip.

Delete a voice

Deletes one of your own voices. A published voice is also removed from the public voice library.

Response:

Deprecated personal voice endpoints

The /personal-voices endpoints are deprecated. They keep working for existing integrations, but new code should use the /voices endpoints. Deprecated responses include a Deprecation header and a Link header that points to the replacement.

GET /personal-voices and POST /personal-voices still return the original { id, name, sampleUrl } shape. Their id is the legacy pv: id when the voice has one.

Responses

Successful generate-speech requests return an MP3 file.

Errors return JSON with an error message:

If a request fails, check that your API key is valid, the voiceId exists, and the request includes either text or ssml.

Testing tips

• Make API requests from a server environment, not browser code.
• Start by calling /voices and copying a voice ID from the response.
• Save generate-speech responses with --output speech.mp3.
• Keep SSML valid XML. Escape quotation marks correctly when sending SSML inside JSON.