API Documentation

Beta

Convert text to audiobook-quality audio programmatically. This API is in beta — endpoints and response shapes may change.

Authentication

All API requests require an API key. Generate one from your Settings page.

Include your key in the Authorization header:

Authorization: Bearer aw_your_api_key_here

Base URL

https://www.audiowaveai.com/api/v1

Playlists

GET/playlists

List all your playlists

curl https://www.audiowaveai.com/api/v1/playlists \
  -H "Authorization: Bearer aw_your_api_key_here"

Response

{
  "playlists": [
    {
      "id": 1,
      "name": "My Playlist",
      "voice": "echo",
      "trackCount": 3,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

GET/playlists/:id

Get a playlist with all its tracks

curl https://www.audiowaveai.com/api/v1/playlists/{playlistId} \
  -H "Authorization: Bearer aw_your_api_key_here"

Response

{
  "playlist": {
    "id": 1,
    "name": "My Playlist",
    "voice": "echo",
    "trackCount": 2,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "tracks": [
      {
        "id": 42,
        "title": "Chapter 1",
        "contentLength": 1234,
        "order": 1,
        "status": "stitched",
        "audioUrl": "https://...",
        "createdAt": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}

POST/playlists

Create a new playlist

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Name of the playlist
`voice`	string	Optional	Default voice for tracks. Defaults to your account voice

curl -X POST https://www.audiowaveai.com/api/v1/playlists \
  -H "Authorization: Bearer aw_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Playlist"}'

Response

{
  "playlist": {
    "id": 1,
    "name": "My Playlist",
    "voice": "echo",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

Tracks

GET/playlists/:id/tracks

List all tracks in a playlist

curl https://www.audiowaveai.com/api/v1/playlists/{playlistId}/tracks \
  -H "Authorization: Bearer aw_your_api_key_here"

Response

{
  "tracks": [
    {
      "id": 42,
      "title": "Chapter 1",
      "contentLength": 1234,
      "order": 1,
      "status": "stitched",
      "audioUrl": "https://...",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

POST/playlists/:id/tracks

Add a track to a playlist

Request Body

Parameter	Type	Required	Description
`title`	string	Optional	Track title. Defaults to page title (if url) or "Untitled Track"
`content`	string	Optional	The text content to convert to audio. Required if url is not provided
`url`	string	Optional	URL to fetch content from. Extracts clean text using Readability. Required if content is not provided

# With text content
curl -X POST https://www.audiowaveai.com/api/v1/playlists/{playlistId}/tracks \
  -H "Authorization: Bearer aw_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Chapter 1", "content": "The text content to convert to audio..."}'

# With URL (extracts clean text automatically)
curl -X POST https://www.audiowaveai.com/api/v1/playlists/{playlistId}/tracks \
  -H "Authorization: Bearer aw_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paulgraham.com/start.html"}'

Response

{
  "track": {
    "id": 42,
    "title": "Chapter 1",
    "contentLength": 1234,
    "order": 1,
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

POST/playlists/:id/tracks/:trackId/convert

Convert a track to audio (Server-Sent Events)

This endpoint returns a stream of Server-Sent Events (SSE) reporting progress as each chunk is converted and then stitched together.

Request Body (optional)

Parameter	Type	Required	Description
`voice`	string	Optional	Voice to use. Defaults to the playlist voice

curl -N -X POST https://www.audiowaveai.com/api/v1/playlists/{playlistId}/tracks/{trackId}/convert \
  -H "Authorization: Bearer aw_your_api_key_here" \
  -H "Content-Type: application/json"

SSE Events

data: {"type":"started","trackId":42,"voice":"echo"}

data: {"type":"chunking","totalChunks":5}

data: {"type":"progress","chunk":1,"total":5,"message":"Converted chunk 1 of 5"}

data: {"type":"stitching","message":"Combining audio chunks..."}

data: {"type":"complete","audioUrl":"https://...","duration":120}

Available Voices

We support a wide range of voices from OpenAI and Azure. Browse and preview all available voices on the Voices page. Pass the voice name in the convert request body.

Errors

All errors return JSON with an error field:

{
  "error": "Invalid API key"
}

Status	Description
`401`	Missing or invalid API key
`400`	Invalid request body
`404`	Playlist or track not found
`500`	Server error

Rate Limits

API access is limited by your credit balance. Each character of text converted costs one credit. Check your remaining credits on the Settings page.