API Documentation Preview

Full documentation coming soon. Below is a preview of the API structure. Contact us for early API access.

Overview

The Podlovin API allows you to generate host-read podcast ads from any podcast audio. Send us an episode, we extract the host's voice, and return broadcast-ready ad audio.

Base URL

https://api.podlovin.ai/v1

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx

Key prefixes: pk_live_ for production, pk_test_ for sandbox (watermarked output).

Quickstart

Generate your first ad in three steps:

# 1. Upload podcast (extracts all voices automatically)
POST /v1/podcasts
{
  "source_url": "https://example.com/episode-47.mp3",
  "name": "Coffee Talk - Episode 47"
}

# Response (immediate)
{
  "pod_id": "pod_7x9k2m4n",
  "status": "processing"
}

# Webhook: podcast.ready (when processing completes)
{
  "event": "podcast.ready",
  "pod_id": "pod_7x9k2m4n",
  "data": {
    "voices": [
      { "voice_id": 0, "speaking_percent": 65.2, "is_primary": true },
      { "voice_id": 1, "speaking_percent": 28.2 }
    ]
  }
}

# 2. Generate ad using extracted voice
POST /v1/generate
{
  "pod_id": "pod_7x9k2m4n",
  "voice_id": 0,
  "script": "Try Acme Coffee. Use code PODCAST for 20% off."
}

# Webhook: generation.complete
{
  "event": "generation.complete",
  "gen_id": "gen_xyz789",
  "data": {
    "audio_url": "https://cdn.podlovin.ai/output/gen_xyz789.mp3",
    "duration_sec": 8.4
  }
}

Generate Ad

POST /v1/generate

Generate an ad read using a voice from an uploaded podcast. Results delivered via webhook.

Request Body

Parameter	Type	Description
`pod_id`	string	Podcast ID from upload (required)
`voice_id`	int	Speaker index: 0, 1, 2... (required)
`script`	string	Ad copy to generate, max 500 chars (required)
`options.style`	string	conversational \| energetic \| calm (default: conversational)
`options.speed`	float	0.8 - 1.2 (default: 1.0)

Podcasts

POST /v1/podcasts

Upload a podcast episode. Voices are automatically extracted via speaker diarization.

GET /v1/podcasts/{pod_id}

Get podcast manifest including all detected voices and quality scores.

Voices

GET /v1/podcasts/{pod_id}/voices

List all voices detected in a podcast.

GET /v1/podcasts/{pod_id}/voices/{voice_id}

Get voice details including extracted reference clips and quality scores.

Generations

GET /v1/generations/{gen_id}

Get generation details and download the output audio URL.

Webhooks

All async operations deliver results via webhooks:

podcast.ready - Podcast processed, voices extracted
podcast.failed - Processing failed
generation.complete - Ad audio ready
generation.failed - Generation failed

Ready to get started?

Request API access and we'll get you set up.

Get API Access