Skip to navigation
FormantAI Voice APIPodcast

Submit an episode from an uploaded PDF

View as Markdown

Queues an episode whose source material is extracted from a PDF already uploaded through POST /v1/podcast/uploads. The PDF is read from storage server-side and must be 10 MB or smaller; a larger file is rejected as 400.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
source_keystringRequired<=200 characters

Key returned by POST /v1/podcast/uploads.

focus_querystringRequired<=5000 characters
What the episode should focus on within the PDF.
speakerslist of objectsRequired
One to four voices.
num_segmentsintegerOptional1-20Defaults to 2
Number of outline segments.
episode_namestringOptional<=200 charactersDefaults to episode
Output filename stem.
briefingstringOptional<=5000 charactersDefaults to
Instructions or angle for the episode.
languagestring or nullOptional<=200 characters

Language name (Hindi, english) or locale code (hi-IN, en-IN), any case. Normalized to the locale code the voice providers expect; an unrecognized value is rejected with 400.

output_formatenumOptionalDefaults to mp3

Container of the finished episode. mp3 is audio only. mp4 carries the same audio (AAC) with a still black H.264 video track cut to the audio’s length, for platforms that only ingest video, such as Cloudflare Stream.

Allowed values:
tts_providerenumOptional

Text-to-speech provider that voices the episode. elevenlabs renders the voices on the ElevenLabs account behind your workspace’s connection. sarvam renders 37 bulbul:v3 speakers and 222 bulbul:v4-flash persona voices across eleven Indic languages plus Indian English. smallest renders 249 voices across 30+ languages. vakyam renders Vakyam’s Indic voices and speaks Hindi unless language is set. The connection behind the provider is resolved server-side from your own workspace, so no connection id is accepted. Omit it to use your deployment’s default provider.

Allowed values:
tts_modelenumOptional

Text-to-speech model. Must be selectable for tts_provider: eleven_multilingual_v2 (default), eleven_flash_v2_5, eleven_turbo_v2_5, eleven_v4 or eleven_v4_turbo for elevenlabs; bulbul:v3 (default) or bulbul:v4-flash for sarvam; lightning_v3.1_pro for smallest; raaga-v1 for vakyam. Omit it and the provider’s default (its first model) is used. A model that does not belong to the chosen provider is rejected at submit with 400 invalid_request; nothing is rendered or billed.

Response

Episode accepted and queued
idinteger
Episode id. Poll it to collect the audio.
statusenum

Always pending on submit — rendering runs asynchronously.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error