Podcast

Use the podcast API to turn source material — a block of text or an uploaded PDF — into a scripted, multi-speaker audio episode. An LLM writes an outline and a transcript, every turn is synthesized with the voice you assigned to that speaker, and the clips are concatenated into one MP3 at 128 kbps, 44.1 kHz — or, with output_format: "mp4", an MP4 ready for video platforms such as Cloudflare Stream.

Rendering is asynchronous and takes minutes. Every submission returns an episode id immediately, and polling that id is the only way to collect the audio. There is no webhook, no callback, no episode list, and no cancel endpoint.

How it works

Base URLs and authentication

Use the global production API unless your workspace is provisioned in the India region. An episode id is only resolvable on the deployment it was created on, so poll the same base URL you submitted to.

Every request needs an API key as a bearer token. Keys are created in the dashboard under Developer -> API Keys and are shown once.

Authorization: Bearer YOUR_API_KEY

A missing header, a scheme other than Bearer, an empty token, an unknown key, and a disabled key all return the same 401 authentication_error.

Endpoints

All four are JSON. There is no multipart endpoint: a PDF is uploaded straight to storage, never through the API.

Submit an episode from text

POST /v1/podcast/jobs

Content type: application/json.

curl -X POST "https://api.voice.formantai.com/v1/podcast/jobs" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quarterly results: revenue grew 18% year on year, driven by ...",
    "briefing": "A two-host recap for listeners who do not work in finance. Warm, concrete, no jargon.",
    "episode_name": "q3-recap",
    "num_segments": 3,
    "language": "en-IN",
    "speakers": [
      {
        "name": "Asha",
        "voice_id": "priya",
        "backstory": "Equity analyst covering consumer tech.",
        "persona": "Precise, asks the sharp follow-up."
      },
      {
        "name": "Ravi",
        "voice_id": "aditya",
        "persona": "Curious generalist, keeps it plain-spoken."
      }
    ]
  }'

{
  "id": 4821,
  "status": "pending"
}

Request an upload URL

POST /v1/podcast/uploads

curl -X POST "https://api.voice.formantai.com/v1/podcast/uploads" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "annual-report.pdf"}'

{
  "upload_url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
  "key": "pdf/3f2a9c1b8e4d47a1b0c5d6e7f8091a2b_annual-report.pdf",
  "expires_in": 900,
  "content_type": "application/pdf"
}

Submit an episode from a PDF

POST /v1/podcast/jobs/pdf

Content type: application/json. The PDF itself is not in this request — only its key.

There is no content field here: the content is extracted from the PDF by the renderer.

curl -X POST "https://api.voice.formantai.com/v1/podcast/jobs/pdf" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_key": "pdf/3f2a9c1b8e4d47a1b0c5d6e7f8091a2b_annual-report.pdf",
    "focus_query": "Cover the outlook section and the risks the auditors flagged.",
    "briefing": "Two analysts talking it through, sceptical but fair.",
    "episode_name": "annual-report-brief",
    "speakers": [
      {"name": "Asha", "voice_id": "priya"},
      {"name": "Ravi", "voice_id": "aditya"}
    ]
  }'

{
  "id": 4822,
  "status": "pending"
}

Poll an episode

GET /v1/podcast/jobs/{id}

curl "https://api.voice.formantai.com/v1/podcast/jobs/4821" \
  -H "Authorization: Bearer $FORMANT_API_KEY"

Polling reads the stored episode record directly, so it keeps working while the renderer is busy or restarting.

While the episode is still rendering:

{
  "id": 4821,
  "status": "processing",
  "episode_name": "q3-recap",
  "error": null,
  "duration_seconds": null,
  "audio_url": null,
  "audio_url_expires_in": null
}

When it is done:

{
  "id": 4821,
  "status": "completed",
  "episode_name": "q3-recap",
  "error": null,
  "duration_seconds": 784.32,
  "audio_url": "https://storage.googleapis.com/...&X-Goog-Signature=...",
  "audio_url_expires_in": 900
}

When it failed:

{
  "id": 4821,
  "status": "failed",
  "episode_name": "q3-recap",
  "error": "sarvam tts failed (400) [speaker=emily model=bulbul:v3 lang=en-IN ...]",
  "duration_seconds": null,
  "audio_url": null,
  "audio_url_expires_in": null
}

Source material

An episode is built from exactly one of two sources.

Inline text

Put the whole source in content — up to 200,000 characters — and describe the angle in briefing. Nothing else is fetched: the episode is written only from what you send.

The PDF upload flow

The PDF goes straight to object storage and is submitted by key, so the file never travels through the API.

UPLOAD=$(curl -s -X POST "https://api.voice.formantai.com/v1/podcast/uploads" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "annual-report.pdf"}')
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .upload_url)
KEY=$(echo "$UPLOAD" | jq -r .key)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --upload-file annual-report.pdf
curl -X POST "https://api.voice.formantai.com/v1/podcast/jobs/pdf" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source_key\": \"$KEY\",
       \"focus_query\": \"Cover the outlook section and the risks the auditors flagged.\",
       \"speakers\": [{\"name\": \"Asha\", \"voice_id\": \"anushka\"}]}"

Rules the PUT must follow:

• Method. The URL is signed for PUT only. A POST or a GET to it is rejected by storage.
• Content type. application/pdf, exactly. The content type is part of what the URL is signed over, so any other value — including a client’s default application/octet-stream — fails the signature check.
• One object. The URL writes the returned key and nothing else. You cannot aim it at another object, and you cannot choose the key yourself.
• Validity. 15 minutes (expires_in: 900), counted from the moment the URL was issued. When it expires, request a new one; the old key is then useless because nothing was written to it.
• Body. Raw PDF bytes, not multipart and not base64.

At submit, only the key is passed back. It is validated against the exact shape the upload endpoint mints, pdf/<32 hex characters>_<safe filename>, and anything else is rejected with 400 invalid_request — you cannot point source_key at an arbitrary object. A well-formed key with no object behind it returns 404 not_found.

The uploaded PDF is read once, when the episode is submitted. That is where the 10 MB ceiling is enforced, because a signed upload cannot cap what a client sends: an oversized file uploads successfully and is then refused at submit. The renderer reads the document in two passes — one over the whole file for context, one for the material your focus_query asks about — and the combined result becomes the episode’s content.

Speakers

speakers describes the cast. Order is the order the LLM is told about them; it does not force who speaks first.

Rules enforced at submit:

• Between 1 and 4 speakers. Zero, or five or more, is rejected.
• Names must be unique. Two speakers called Asha return 400 invalid_request, because the renderer maps a transcript line back to a voice by name.
• Voice ids must be unique. Two speakers sharing a voice_id return 400 invalid_request — an episode where two people sound identical is assumed to be a mistake.

backstory and persona change the script, never the audio directly. They are the right place for direction such as “sceptical, interrupts to ask for numbers”.

Voice ids

voice_id is whatever the provider calls a voice: an ElevenLabs voice id, a Sarvam speaker name, a Smallest voice id, a Vakyam voice name. It is passed through unchanged, so it must belong to the provider you selected with tts_provider — a Sarvam speaker will not work on a Smallest episode. Every valid value is listed in the Voice catalogue.

The same lists are in the dashboard under an agent’s Voice tab, where you can preview a voice before using it, and programmatically from the dashboard API as GET /synthesizer-voices.

TTS providers

tts_provider picks who voices the episode. Four providers are available:

The connection behind the provider is resolved server-side from your own workspace’s connections, so the API takes no connection id. Omit tts_provider and the episode uses your deployment’s default provider.

An unknown value is rejected at submit with 400 invalid_request naming the ones that are valid. Nothing is rendered and nothing is billed.

TTS models

tts_model must be selectable for the provider you chose. Omit it and the first model in the provider’s row is used.

Set tts_model to pick a model other than the default — for example bulbul:v4-flash or eleven_v4. A model that is not selectable for the chosen provider is rejected at submit with 400 invalid_request, and the message names the models that are. Nothing is rendered and nothing is billed.

Language

language accepts a language name or a locale code, in any case: Hindi, hindi, hi and hi-IN all mean Hindi. It is normalized at submit to the locale code the voice providers expect — English and the Indic languages get the -IN region (hindi → hi-IN, english → en-IN), and a region you send yourself is kept (en-US, pt-BR). An unrecognized value is rejected with 400 invalid_request before anything is rendered or billed.

It does two things:

• The script. When set, the outline and transcript are written in that language. When omitted, they follow the language of your content and briefing.
• The audio. The normalized code is passed to the TTS provider with every turn. Sarvam falls back to en-IN when it is absent, Smallest to en and Vakyam to hi-IN. ElevenLabs is not sent a language code; it speaks the language the text is written in.

Give each speaker a voice that covers the language: nothing cross-checks the two, and a mismatch shows up as mispronounced audio or a provider error mid-render.

Output format

output_format chooses the container of the finished episode:

The two carry the same episode and are billed the same: duration_seconds is the audio length either way.

Voice catalogue

Every voice_id accepted by the podcast API, per provider. A voice belongs to one provider only — pass it with the matching tts_provider.

Custom and cloned voices

voice_id is not an open field. Every provider rejects an id that is not in its own catalogue, at the first synthesis call:

• ElevenLabs voices belong to the ElevenLabs account behind your workspace’s connection. A voice from another account — including a clone on your own ElevenLabs account — is not visible to it, and the episode fails.
• Sarvam has a fixed roster and no cloning. An unknown speaker returns Speaker '<id>' is not recognized, and the episode fails.
• Smallest supports voice cloning, but a cloned voice belongs to the Smallest account it was created on. Rendering uses the API key on your workspace’s synthesizer connection, so a voice cloned on your own Smallest account is not visible to it and returns Voice '<id>' is not available on the lightning_v3.1_pro model.

To use a cloned voice, the clone has to live on the account behind the connection your workspace renders with. That means bringing your own ElevenLabs or Smallest connection, with your own API key, rather than the shared platform one — talk to support to have one attached to your workspace. Once it is, your cloned voices appear alongside the catalogue below and can be passed as voice_id like any other.

ElevenLabs voices

ElevenLabs voice ids are 20-character ids such as 21m00Tcm4TlvDq8ikWAM. Which ones work depends on the ElevenLabs account behind your workspace’s connection: its premade voices plus any voices added to that account. Look them up in the dashboard under an agent’s Voice tab, or with GET /synthesizer-voices. Every ElevenLabs voice works with every selectable ElevenLabs model.

Sarvam voices (bulbul:v3)

37 speakers. Each one covers all eleven supported languages: bn-IN, en-IN, gu-IN, hi-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN. Set which one is spoken with language.

Female (14) — ritu, priya, neha, pooja, simran, kavya, ishita, shreya, roopa, tanya, shruti, suhani, kavitha, rupali

Male (23) — aditya, ashutosh, rahul, rohan, amit, dev, ratan, varun, manan, sumit, kabir, aayan, shubh, advait, anand, tarun, sunny, mani, gokul, vijay, mohit, rehan, soham

Sarvam voices (bulbul:v4-flash)

222 persona voices, named <name>_<language>_<style> — for example ritu_hi_customer is Ritu, speaking Hindi, in a customer-support style. Unlike the bulbul:v3 speakers, each persona speaks the language in its name; Hinglish personas (enhi) cover both English and Hindi. Pass the whole name as voice_id, with tts_model: "bulbul:v4-flash".

Smallest voices (lightning_v3.1_pro)

249 voices. Most are multilingual; they are grouped below by the language Smallest recommends them for, which is the one they sound most natural in.

Vakyam voices (raaga-v1)

Vakyam voice names, such as Archana, passed through unchanged. Names are case-sensitive, and an unknown name fails the episode mid-render, like any other provider. Vakyam renders at 24 kHz; the episode is still encoded at 44.1 kHz like every other.

Job lifecycle

Recommended polling

Poll every 5 to 10 seconds. A render writes an outline, writes a transcript segment by segment, synthesizes every turn, and concatenates the clips, so minutes are normal and seconds are not.

import os
import time
import requests
BASE_URL = "https://api.voice.formantai.com"
HEADERS = {"Authorization": f"Bearer {os.environ['FORMANT_API_KEY']}"}
DEADLINE_SECONDS = 1800
POLL_SECONDS = 10
TERMINAL = {"completed", "failed"}
def submit(payload):
    """Submit an episode and return its id."""
    response = requests.post(
        f"{BASE_URL}/v1/podcast/jobs", headers=HEADERS, json=payload, timeout=200
    )
    response.raise_for_status()
    return response.json()["id"]
def wait_for(episode_id):
    """Poll an episode until it reaches a terminal status or the deadline passes."""
    deadline = time.monotonic() + DEADLINE_SECONDS
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/podcast/jobs/{episode_id}", headers=HEADERS, timeout=30
        )
        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", POLL_SECONDS)))
            continue
        if response.status_code >= 500:
            time.sleep(POLL_SECONDS)
            continue
        response.raise_for_status()
        job = response.json()
        if job["status"] in TERMINAL:
            return job
        time.sleep(POLL_SECONDS)
    raise TimeoutError(f"episode {episode_id} did not finish within {DEADLINE_SECONDS}s")
job = wait_for(submit({
    "content": open("q3-notes.txt").read(),
    "briefing": "A two-host recap for listeners who do not work in finance.",
    "episode_name": "q3-recap",
    "num_segments": 3,
    "speakers": [
        {"name": "Asha", "voice_id": "priya", "persona": "Precise, asks the sharp follow-up."},
        {"name": "Ravi", "voice_id": "aditya", "persona": "Curious generalist."},
    ],
}))
if job["status"] == "failed":
    raise RuntimeError(job["error"])
audio = requests.get(job["audio_url"], timeout=120)  # no auth header
open(f"{job['episode_name']}.mp3", "wb").write(audio.content)  # .mp4 if you asked for output_format "mp4"

The audio URL

audio_url is a signed link to the episode in private storage, valid for 900 seconds (15 minutes) from the moment that poll response was built.

• Fetch it without an Authorization header. The signature is the credential; adding a bearer token is unnecessary and can break the request.
• It plays inline. The object is stored as audio/mpeg (or video/mp4) with no attachment disposition, so it works directly in a browser or an <audio>/<video> element, and storage serves range requests, so a player can seek.
• It is a bearer capability. Anyone holding the link can download the episode until it expires. Do not paste it into shared logs or tickets.
• When it expires, poll again. GET /v1/podcast/jobs/{id} mints a fresh link on every call for a completed episode. The audio itself is not deleted, only the link expires.

Download promptly, or store the bytes yourself. There is no permanent public URL.

Limits

A field outside its bounds is rejected with 422 — after the 32 MB body check (413) and the API-key check (401), which both run before the body is parsed, and before anything reaches the renderer.

Rate limiting

Rate limiting is per workspace, defaulting to 50 requests per minute, and the bucket is shared with every other endpoint on this API — calls, batch calls, conversations and transcription draw from the same budget as submitting and polling episodes. It is a token bucket that refills continuously.

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 48
X-RateLimit-Reset: 2026-03-18T20:54:00.917640+00:00

The headers are absent on responses rejected before the key is checked, such as 401 and 413, so treat them as optional when parsing.

Episode length

Episode length is not proportional to num_segments. The renderer targets a fixed window of roughly 12 to 15 minutes of spoken dialogue — about 1,800 to 2,250 words at 150 words per minute — and divides that budget across the segments you asked for. The episode never has more segments than you asked for: if the outline comes back with extra, they are folded into the last one. Each segment also has a floor of 200 words, so above about 9 segments the floor takes over and the episode does get longer.

num_segments therefore controls structure, not duration: more segments means more, shorter topic blocks. The true length of what was rendered comes back as duration_seconds.

Billing

Submitting an episode places a credit hold of 26 minutes × your per-minute podcast rate — ₹156 at ₹6 per minute. If the balance cannot cover the hold, the submission is refused with 402 insufficient_credits and nothing is rendered.

When the episode finishes, the hold is settled against the audio actually produced, billed per started minute — a 61-second episode bills as two minutes. A normal 12–15 minute episode is refunded the rest of the hold. An episode longer than the hold is debited the extra only down to a zero balance; a podcast never takes your balance negative. A failed episode settles at zero, so the whole hold comes back.

Each episode holds its own credit, so episodes submitted in parallel need the hold for each one: three at ₹6 per minute need ₹468 available, and a submit that the remaining balance cannot cover gets 402 while the others render.

Errors

Every error except 422 uses the standard envelope:

{
  "error": {
    "message": "each speaker must use a distinct voice_id",
    "type": "invalid_request"
  }
}

A 429 adds one extra key inside the same object:

{
  "error": {
    "message": "rate limit exceeded. 50 requests per minute allowed.",
    "retry_after_seconds": 2,
    "type": "rate_limit_exceeded"
  }
}

A 422 comes from request parsing and uses FastAPI’s own shape instead, with a detail array and no type:

{
  "detail": [
    {
      "input": 25,
      "loc": ["body", "num_segments"],
      "msg": "Input should be less than or equal to 20",
      "type": "less_than_equal"
    }
  ]
}

Retry 429 after Retry-After, and 500 with bounded exponential backoff. Do not retry 400, 401, 402, 404, 413 or 422 until the request itself is fixed.

Troubleshooting

Next steps