API Documentation Preview

Below is a preview of the API structure. Contact us for early API access.

Overview

The Podlovin API provides two core capabilities: generating host-read podcast ads from any episode, and translating episodes into 10 languages in the host's own voice. Send us audio, we handle the rest.

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 or translate an episode:

quickstart.sh

# 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 }
    ]
  }
}

# 2a. 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."
}

# 2b. Or translate the episode
POST /v1/localize
{
  "pod_id": "pod_7x9k2m4n",
  "voice_id": 0,
  "languages": ["es", "fr", "ja"]
}

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.

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)

Generations

GET /v1/generations/{gen_id}

Get generation details and download the output audio URL.

Localize

POST /v1/localize

Translate a podcast episode into one or more languages. Podlovin separates vocals from background audio, translates the speech in the host's voice, and recombines with the original background. 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)
`languages`	string[]	Target language codes (required, see below)
`options.preserve_background`	bool	Separate and recombine background audio (default: true)

Supported Languages

Chinese zh French fr German de Italian it Japanese ja Korean ko Portuguese pt Russian ru Spanish es English en

Localizations

GET /v1/localizations/{loc_id}

Get localization details including output audio URLs for each language.

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
localization.complete — Translated audio ready
localization.failed — Localization failed

Ready to get started?

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

Get API Access