# podkst.ai API

> AI-powered multi-speaker podcast generation engine. Convert any text, URL, or topic into a professionally produced podcast with natural-sounding voices.

## Authentication

All API requests require an API key passed via the `x-api-key` header.

Create API keys at https://podkst.ai (Dashboard → Settings → API Keys).

### Scopes (minimum for agents)

API keys carry scopes that gate each endpoint. Autonomous agents that generate podcasts and read back their own jobs need **only** `generate:podcast` — it implies self-read on the single-generation endpoint. A key with only `generate:podcast` can create jobs via POST /v1/generations and read the jobs it created via GET /v1/generations/{id}. Jobs created by a different key on the same account are not visible.

Use `read:jobs` only if the key needs to read jobs created by **other** keys on the same account. `read:voices` is required for GET /v1/voices. `billing:read` is required for GET /v1/credits.

## Base URL

https://api.podkst.ai

## Endpoints

The public API exposes exactly four operations. These are the only
methods intended for agent and third-party use. All other routes are
internal account-management surface and are not documented here.

### 1. Generate a Podcast
POST https://api.podkst.ai/v1/generations

Creates an async podcast generation job. Returns immediately with a job ID. Poll the status endpoint or register a webhook for completion.

Request body (JSON):
- input (string, required): Text content, URL, or topic to convert into a podcast (10–50,000 chars)
- tier: "flash" | "regular" | "deep-dive" (default: "regular"). Alias: "coverage" (deprecated, use "tier")
- language: "pt-BR" | "en-US" (default: "pt-BR")
- style: "conversational" | "interview" | "narrative" | "educational" (default: "conversational")
- mode: "full" | "script_to_audio" (default: "full"). "full" = LLM pipeline + TTS. "script_to_audio" = TTS from pre-written script.
- format: "dialogue" | "monologue" (default: "dialogue"). "dialogue" = two-host conversation. "monologue" = single-voice narration.
- speakers: Array of **exactly 2** objects with voice (display name string) and optional tone (string). Default: [{voice: "Nina", tone: "analytical"}, {voice: "Kai", tone: "enthusiastic"}]. Required for format="dialogue". Do NOT send for format="monologue".
- voice: Single voice display name (string). Required for format="monologue". Ignored for format="dialogue".
- script: Object with { title, description?, text }. Required for mode="script_to_audio". The text field must use "Label: dialogue" format where each speaker label matches the name field in the speakers array. Example: `"text": "Nina: Welcome!\nKai: Hello!"` with `"speakers": [{"voice": "Nina"}, {"voice": "Kai"}]`. Labels are case-sensitive and positionally bound to speakers.
- tts_quality: "standard" | "pro" (default: "pro")
- emotion_annotations: boolean (default: true)
- webhook: URL for completion notification (HTTPS required)
- webhook_events_filter: Array of "started" | "progress" | "completed" | "failed"

Response: { id, status, created_at, urls: { get, cancel } }

### 2. Check Generation Status
GET https://api.podkst.ai/v1/generations/{id}

Returns generation details including status, progress percentage, and output (audio_url, duration, script) when completed.

### 3. List Available Voices
GET https://api.podkst.ai/v1/voices

Optional query: gender ("male" | "female")

Available voices (30 total):

Female:
- Nina — Firm
- Luna — Breezy
- Mia — Youthful
- Aria — Bright
- Jade — Easy-going
- Zara — Bright
- Vera — Smooth
- Clara — Clear
- Nora — Upbeat
- Lily — Soft
- Alma — Mature
- Eva — Forward
- Iris — Gentle
- Rosa — Warm

Male:
- Kai — Upbeat
- Leo — Informative
- Rio — Excitable
- Max — Firm
- Enzo — Breathy
- Nico — Clear
- Ravi — Easy-going
- Omar — Smooth
- Dante — Gravelly
- Hugo — Informative
- Axel — Firm
- Ivan — Even
- Luca — Friendly
- Teo — Casual
- Marco — Lively
- Soren — Knowledgeable

### 4. Check Credit Balance
GET https://api.podkst.ai/v1/credits

Returns current credit balance, plan info, and usage.

## Quick Start

```bash
# Generate a podcast from a URL
curl -X POST https://api.podkst.ai/v1/generations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/article",
    "language": "en-US",
    "style": "conversational",
    "speakers": [
      {"voice": "Nina", "tone": "analytical"},
      {"voice": "Kai", "tone": "enthusiastic"}
    ]
  }'

# Check status (poll until status is "succeeded")
curl https://api.podkst.ai/v1/generations/JOB_ID \
  -H "x-api-key: YOUR_API_KEY"
```

## Pricing

Formula (ADR-011): ceil(duration_min × tier_rate × tts_mult) + research_fee.
- tier_rate: flash=2/min, regular=4/min, deep-dive=6/min
- tts_mult: standard=1, pro=2
- research_fee: 3 × search_calls (flash=1, regular=2, deep-dive=3)
- script_to_audio: ceil(duration_min × 2 × tts_mult), min 1 credit

Check your balance via GET /v1/credits.

## Links

- OpenAPI spec: https://api.podkst.ai/openapi.json
- Interactive docs: https://api.podkst.ai/docs
- Dashboard: https://podkst.ai