Podcasts

/api/v1/podcasts creates the same podcasts as the Mini App, in any of the three script modes. A finished podcast appears in the owner’s library as private and is published only from the Mini App.

Endpoints

Method and path	Scope	Result
GET /api/v1/podcasts/voices	podcasts:quote	available voices
POST /api/v1/podcasts/quotes	podcasts:quote	201 {quote}
POST /api/v1/podcasts	podcasts:create	202 {operation: {podcastId, taskId, status, created, creditsCharged}}
GET /api/v1/podcasts/:podcastId	podcasts:read	{podcast} with status, stageCode, plan progress and available recovery/accounting
GET /api/v1/podcasts/:podcastId/receipt	podcasts:read	{receipt}
POST /api/v1/podcasts/:podcastId/cancel	podcasts:create	{success: true}
POST /api/v1/podcasts/:podcastId/continuation-quote	podcasts:quote	201 {quote} for an admissible failed task
POST /api/v1/podcasts/:podcastId/continue	podcasts:create	202 {operation} for the same task
GET /api/v1/podcasts/:podcastId/audio	podcasts:read	audio, supports Range

Modes

• prepared_text (default) — your text is narrated as written.
• raw_text — an agent turns rough notes into narration.
• topic — an agent writes the script on a topic; with grounding: "quick" or "deep" it first searches and reads sources. For a researched topic, the podcast status shows the research summary.

grounding: "none" uses general model knowledge without search, freshness checks or source verification. Every mode uses the current plan; unsupported configuration is refused before paid work. Prepared text is narrated completely after whitespace normalization; rough-note preparation preserves the substantive content and ending of the original.

Quick/Deep search the topic without a mandatory news period and automatically read discovered pages within the spending budget and actual provider limits. Complete originals are retained; agents read the needed pages without another extraction. The script uses supported materials or selected library versions; search snippets are insufficient. Without usable evidence, the episode stops before writing or synthesis; repeating the same material will not resolve the cause. Narrow the topic or supply usable pages in urls, then request a new quote. You can also pass sourceVersionIds for your existing saved sources; create or update the library in the Mini App. A known URL refusal during agent reading does not prevent admissible pages in the batch from being read. The agent receives a safe reason and can select another source; a forbidden URL is neither dispatched nor charged as a read. Retained originals are reused before a fresh DNS check, while every new request and redirect retains network safety checks. Unknown paid effects, cancellation and financial or operator refusals do not become ordinary source errors. The remaining material must still be assessed for substantive adequacy. A retained error from an individual search or extraction is returned to the author as data. The author can continue from other genuine originals or make a different permitted request. The original uncertain request is not dispatched again, including in another read batch containing the same URLs. An error does not replace a read source. An episode may be ready to play while the earlier request’s expense remains in reconciliation with its hold retained. An unused search or extraction provider disabled by the operator does not block quoting or scenario selection with usable originals from your library. Agents read retained originals without a new external request. If an evidence gap requires a new search or extraction, provider availability is checked before a paid call or dispatch. Script writing and synthesis remain new work charged from actual usage. Without an extraction route or usable library text, quoting returns 503 RESEARCH_EXTRACTION_UNAVAILABLE before paid work. If you use only web sources, wait for the operator to restore extraction and request a new quote. Confirmed calls in an accepted task are charged from actual usage even if the research yields no usable material.

Request fields

Field	Modes	Meaning
mode	all	prepared_text, raw_text or topic
title	all	a nonempty title
text	prepared_text, raw_text	source text
topic	topic	the subject
voiceId, language	all	a voice from /voices; ru or en
durationMinutes	all	an integer 3–60; a guide to topic depth and estimated duration. Text modes derive an estimate from the source and voice rate when omitted. Minutes do not limit source length, block count or output length; actual duration is measured from audio
lengthPreset	topic	express, standard or detailed; a topic request needs lengthPreset or durationMinutes
grounding	topic	none (default), quick or deep
focus, urls	topic with research	research focus and public HTTP(S) URLs to read
sourceVersionIds	topic with research	versions of your saved sources (rsv_…)
templateId, templateRevision	all	a built-in template or your tpl_…
quality	all	economy, balanced (default) or quality
maximumCredits	all	optional positive safe integer credit limit; omitted or null means balance-funded work without an episode cap; forecasts never reduce it

Any other field returns 400 UNSUPPORTED_API_FIELD before any work. Model selection, reuse of an earlier research run or script, and a user ID are not part of the public contract; other users’ sources and templates are rejected. In the Mini App, retained research and a ready script are selected independently of source privacy. A lawful public corpus is available without new search, while writing a new script still requires available model routes. Voicing a ready script has no search or model dependency. Quotation checks the owner’s authority to use retained materials or a script. The catalog supplies configuration choices; the selected request’s quote determines availability and approximate cost. A configured provider does not certify a successful live call.

After research, the author prepares one complete narration. Rough notes use one text-preparation stage; prepared narration goes directly to voice synthesis. The author owns source support, completeness, language and coherence. Separate mandatory reviews for every block and semantic certificates are not required. Code checks response structure, material ownership and retained results. The common research instruction asks the author to preserve what each number counts, its unit and period, distinguishing plans or capacity from results and intentions from completed actions. The author checks the final memo and wording against originals in the same call; no separate paid review is added.

Narration is not stretched to an estimated size. Words, characters, tokens, minutes and source counts are guides and do not by themselves cause refusal or paid rewriting. A shorter substantive episode is valid; rough-note preparation preserves the substantive details and the original ending. Content quality depends on model decisions and is not guaranteed by code. Completed text is retained for continuation. A known response cut off by the model’s output limit continues from its saved prefix without repurchasing the beginning. An unknown outcome of an already dispatched request requires reconciliation and does not authorize an automatic repeat. New model routes require a confirmed context of at least 200,000 tokens and tool support; accepted tasks retain their routes and tariffs.

A new Podcast quote shows an approximate cost (expectedCredits) separately from the spending limit (maximumCredits, or null without an episode cap). Create does not reserve the full limit: each paid request is charged from its actual result. If the balance cannot fund the next request, status and stageCode become paused_insufficient_credits; balancePause contains the required and available amounts. A top-up resumes the same taskId without a new create call. A top-up does not lift OPERATION_SPENDING_LIMIT. The owner of an admissible failed Podcast may confirm a higher limit or its removal through Continue in the Mini App on the same task and financial operation, without repurchasing completed actions. The creating API key can use continuation-quote and continue; fields and request order are described in Status and continuation. API_KEY_QUOTA_EXCEEDED remains a separate key constraint. During a model-service funding wait, a valid retained marker is returned as recovery: {state: "waiting", reasonCode}. PROVIDER_FUNDING_READ_UNAVAILABLE means funding cannot temporarily be read; PROVIDER_FUNDING_INSUFFICIENT means waiting for service availability to recover. This pause requires neither a customer top-up nor a new create or Continue: the system automatically resumes the same taskId and financial operation when conditions recover. The status does not become failed merely because of this wait. The voice stage may also wait with VOICE_PROVIDER_WAITING or VOICE_LOCAL_COMPLETION_WAITING: the system automatically continues the same task and reuses retained audio without purchasing it again. These waits require neither a top-up nor Continue; their causes and retry boundaries are described in Status and continuation. The owner detail may also include accounting.capturedCredits and accounting.heldCredits: actual cumulative charges and the current outstanding hold from the original receipt. The hold includes exposure retained for an unknown effect until evidence resolves it. Fields are supplied only when the receipt has trustworthy amounts; absence does not mean zero expense. These facts are read only after owner and exact creating-key checks. An already dispatched unknown effect remains protected; a missing ID or monetary observation does not by itself authorize another model request. Cancellation closes admission for new work. An already atomically admitted model request completes and retains its actual expense without starting further work or audio. An unknown outcome retains its hold until authentic reconciliation; a cancelled task cannot Continue.

Examples

A topic with quick search

podcasts:quote, podcasts:create

1 · quote

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "topic",
  "title": "Quantum sensors",
  "topic": "How quantum sensors work and where they are used today",
  "lengthPreset": "express",
  "grounding": "quick",
  "voiceId": "yandex-speechkit:jane",
  "language": "en"
}'

2 · create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "topic",
  "title": "Quantum sensors",
  "topic": "How quantum sensors work and where they are used today",
  "lengthPreset": "express",
  "grounding": "quick",
  "voiceId": "yandex-speechkit:jane",
  "language": "en"
}'

Prepared text

podcasts:quote, podcasts:create

1 · quote

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "prepared_text",
  "title": "Утренний выпуск",
  "text": "Доброе утро. Сегодня три коротких истории о науке и технологиях. Первая — о новых квантовых сенсорах, которые измеряют магнитное поле мозга без громоздких установок. Вторая — о спутниках, которые следят за таянием ледников. Третья — о том, как города учатся экономить воду.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

2 · create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "prepared_text",
  "title": "Утренний выпуск",
  "text": "Доброе утро. Сегодня три коротких истории о науке и технологиях. Первая — о новых квантовых сенсорах, которые измеряют магнитное поле мозга без громоздких установок. Вторая — о спутниках, которые следят за таянием ледников. Третья — о том, как города учатся экономить воду.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

Rough notes

podcasts:quote, podcasts:create

1 · quote

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "raw_text",
  "title": "Итоги недели команды",
  "text": "Заметки: релиз мобильного приложения перенесли на вторник; в поддержку пришло на 20% меньше обращений; новая страница цен подняла конверсию; в пятницу общая встреча в 16:00.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru",
  "durationMinutes": 5
}'

2 · create

curl -s -X POST https://cast.witqq.dev/api/v1/podcasts \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "mode": "raw_text",
  "title": "Итоги недели команды",
  "text": "Заметки: релиз мобильного приложения перенесли на вторник; в поддержку пришло на 20% меньше обращений; новая страница цен подняла конверсию; в пятницу общая встреча в 16:00.",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru",
  "durationMinutes": 5
}'