Potion

Show the account's tier, its limits, and how much of each is used - feeds, episodes and storage. Call this before telling the user whether they have room, or when a call fails on a limit.

get_account

Get one episode's title, description, audio URL, duration and artwork. Use it to show the user a single episode, or to get the audio URL for playback.

get_episode

Get links to Potion's Terms of Service and Privacy Policy. Use it when the user asks what they are agreeing to, or how their data is handled.

get_legal_links

Read what has changed in Potion recently. Useful when a notification points at a new feature, or when you want to know whether a capability exists yet.

get_changelog

List the episodes in a feed, newest first by default. Use it to show the user what is in a feed or to find an episode_id.

list_episodes

List the voices Potion can narrate text with, each with a sample_url the user can listen to. Call this before rendering if the user has any opinion about how it should sound, and offer them the sample rather than describing the voice. Premium voices spend the synthesis allowance five times as fast as standard ones, out of the same allowance - so it is a quantity trade, not a locked feature.

list_voices

List every feed on this Potion account with its id, title and subscribe URL. Call this first when you need a feed_id and do not already have one.

list_feeds

The account's recent render jobs, newest first. Use it to recover a job_id you no longer have, or to see whether anything is still running before starting something new.

list_jobs

Turn text into a narrated episode in a feed. The text you pass is what gets read aloud - send the full article or script verbatim, not a summary of it. This returns a job_id straight away rather than waiting, because rendering an hour of audio takes minutes; expected_wait_seconds in the response says how many. Read it: it is the WAIT, in wall-clock seconds, and it is not the length of the audio - a twelve-minute episode is under a minute of waiting. Tell the user roughly how long, wait, then call get_job once. Check characters_received in the response against what you sent: if it is short, the call was truncated and you should deliver the rest with append_text (pass is_final=false here first, so nothing renders until the whole text has arrived). start_if_under_minutes caps how much audio the job may produce: under the budget it renders as usual, over it the job is held with nothing charged and start_render runs it.

render

Turn a web article into an episode by passing its URL - pass the URL itself, do not fetch the page and paste its text. Potion fetches and extracts it server-side. This does NOT render: it reports how many words it found and roughly how long that would be as audio, so the cost is known before anything is spent. The extracted text is held in a job and start_render is the call that runs it. start_if_under_minutes renders immediately if the article comes to less than that many minutes of audio and holds the job if it is longer. A page that yields too little text is refused with an explanation worth relaying rather than narrated.

ingest_url

Start deleting the whole Potion account - every feed, episode and audio file. Nothing is deleted until the user clicks a confirmation link Potion emails them, so relay that. Poll check_confirmation to see whether they did.

request_account_deletion

Create a Potion account for the user from their email address. Potion emails them a magic link; they must click it before the account exists. Returns a signup_id. Tell the user to check their inbox, then poll check_signup until it confirms and hands back the API key. Use this when the user has no Potion account yet.

start_signup

Runs a render job that is holding text and has not started. A job is in that state after ingest_url, after a render sent with is_final=false, and after a render whose estimate came in over its start_if_under_minutes cap. The synthesis allowance is charged for the audio this produces, and the job carries its own estimate of how much that will be. Progress and the finished episode are in get_job.

start_render

Change a feed's title, description, author, artwork or other settings. Only the fields you send are changed; everything else is left alone.

update_feed

Change an episode's title, description, artwork, publish date or numbering. Only the fields you send are changed.

update_episode