Build with the Podfeed API

Access the same AI pipeline that powers Podfeed's UI. Generate podcast-style audio from text, URLs, files, topics, YouTube videos, and more.

API request and response example

POST /api/v1/audios HTTP/1.1
  x-api-key: <API_KEY>
  Content-Type: application/json

  {
    "inputType": "url",
    "mode": "dialogue",
    "websiteUrl": "https://podfeed.ai",
    "hostVoice": "gemini-archird",
    "coHostVoice": "gemini-achernar",
    "language": "en-US",
    "level": "intermediate",
    "length": "medium",
    "userInstructions": "Prioritize the sections on onboarding and pricing."
  }

  // 202 Accepted
  {
    "task_id": "task_3a8…",
    "status": "processing"
  }

What you can build

The API exposes the same capabilities as the app: content ingestion, AI script generation, and natural TTS output.

Same backend as UI

Full feature parity with the Podfeed app's generation pipeline.

Monologue or dialogue

Pick single voice or two-voice dialogue with host and co-host.

Multiple voice providers

Choose voices from Google, ElevenLabs, OpenAI and more.

Multiple input types

Text, URLs, PDFs, files, topics (research), YouTube, and podcast episode URLs.

Autonomous research

Provide a topic; the API researches and generates a comprehensive episode.

Quick start (Python)

Install the SDK, set PODFEED_API_KEY, and create your first audio.

pip install podfeed-sdk

export PODFEED_API_KEY="your-api-key-here"

from podfeed import (
    PodfeedClient,
    AudioGenerationRequest,
    InputContent,
    VoiceConfig,
    ContentConfig,
)

client = PodfeedClient()  # uses PODFEED_API_KEY env var

task = client.generate_audio(
    request=AudioGenerationRequest(
        input_type="url",
        mode="dialogue",
        input_content=InputContent(url="https://podfeed.ai/faq"),
        voice_config=VoiceConfig(
            host_voice="gemini-puck", cohost_voice="gemini-achird"
        ),
        content_config=ContentConfig(
            level="intermediate",
            length="medium",
            language="en-US",
        ),
    )
)

result = client.wait_for_completion(task["task_id"])  # blocks until done
print(result["result"]["audio_url"])

For more examples, see podfeed-sdk-samples.

API Reference

Complete endpoint reference for the Podfeed REST API. All requests require an API key sent via the x-api-key header.

Authentication

Include your API key in every request using the x-api-key header. You can get a key from your Podfeed dashboard.

x-api-key: your-api-key-here

Base URL: https://api.podfeed.ai

Endpoints

Click an endpoint to see request and response details.

Start an audio generation task from text, URL, file, topic, script, or combined sources.

Field	Type	Required	Description
`inputType`	`string`	required	Type of input content. `fileurltexttopicscript`
`mode`	`string`	required	Audio generation mode. `monologuedialogue` Default: `dialogue`
`websiteUrl`	`string`	optional	Website / YouTube / podcast URL (when inputType="url").
`textContent`	`string`	optional	Plain text up to 50 000 chars (when inputType="text").
`topic`	`string`	optional	Topic for AI-generated research content (when inputType="topic").
`scriptContent`	`string`	optional	Pre-written script up to 100 000 chars (when inputType="script").
`gcsUris`	`string[]`	optional	GCS URIs of pre-uploaded files (when inputType="file"). Get URIs from /upload-urls.
`voice`	`string`	optional	Voice ID for monologue mode.
`hostVoice`	`string`	optional	Host voice ID for dialogue mode.
`coHostVoice`	`string`	optional	Co-host voice ID for dialogue mode.
`language`	`string`	optional	Language code (e.g. "en-US", "es", "fr"). Default: `en-US`
`level`	`string`	optional	Content complexity level. `beginnerintermediateadvanced` Default: `intermediate`
`length`	`string`	optional	Content length preference. `shortmediumlong` Default: `medium`
`userInstructions`	`string`	optional	Custom instructions for content generation.
`voiceInstructions`	`string`	optional	Custom instructions for voice synthesis (supported voices only).
`emphasis`	`string`	optional	Content emphasis or focus area.
`readMode`	`boolean`	optional	Direct text reading mode (no content enhancement). Default: `false`
`feedId`	`string`	optional	Automatically add the generated audio to this feed as an episode.

Field	Type	Required	Description
`task_id`	`string`	optional	Unique identifier for the generation task.
`status`	`string`	optional	Always "processing" on creation. `processing`

Poll the status of a generation task. Returns progress and result when complete.

Field	Type	Required	Description
`task_id`	`string`	required	The task ID returned from the generate endpoint.

Field	Type	Required	Description
`task_id`	`string`	optional	The task identifier.
`status`	`string`	optional	Current task status. `processingcompletedfailed`
`created_at`	`string (ISO 8601)`	optional	When the task was created.
`updated_at`	`string (ISO 8601)`	optional	When the task was last updated.
`error`	`string`	optional	Error message (only when status="failed").
`result`	`object`	optional	Result object (only when status="completed"): { audio_id, audio_url, title, description }.

List all generated audio for the authenticated user.

Field	Type	Required	Description
`limit`	`integer`	optional	Max audios to return (1–100). Default: `20`
`offset`	`integer`	optional	Number of audios to skip. Default: `0`
`status`	`string`	optional	Filter by generation status. `processingcompletedfailed`

Field	Type	Required	Description
`audios`	`array`	optional	Array of audio summaries: { audio_id, title, duration_seconds, status, created_at, file_size_bytes }.
`total_count`	`integer`	optional	Total number of audios (for pagination).
`limit`	`integer`	optional	Limit used in the request.
`offset`	`integer`	optional	Offset used in the request.

Get metadata for a specific audio (URL, title, transcript, duration, etc.).

Field	Type	Required	Description
`audio_id`	`string`	required	The unique identifier of the audio.

Field	Type	Required	Description
`audio_id`	`string`	optional	Audio identifier.
`audio_url`	`string`	optional	Signed URL to download the audio file.
`title`	`string`	optional	Generated or provided title.
`description`	`string`	optional	Content description / summary.
`transcript`	`string`	optional	Full transcript of the audio.
`created_at`	`string (ISO 8601)`	optional	Creation timestamp.
`user_controls`	`object`	optional	Generation parameters used (mode, voice, language, level, length).

Permanently delete a generated audio.

Field	Type	Required	Description
`audio_id`	`string`	required	The unique identifier of the audio to delete.

Field	Type	Required	Description
`success`	`boolean`	optional	true when the audio was deleted.

Get all available voices grouped by language, with provider and cost info.

Field	Type	Required	Description
`{language_code}`	`object`	optional	Top-level keys are language codes (e.g. "en-US", "es", "fr").
`{language_code}.language_name`	`string`	optional	Human-readable language name (e.g. "English").
`{language_code}.voices`	`object`	optional	Map of voice_id → { tts, credits_multiplier, display_name, gender, supported_modes }.

Create a new podcast feed for organizing episodes.

Field	Type	Required	Description
`name`	`string`	required	Name of the podcast feed.
`description`	`string`	optional	Feed description. Default: `My personal podcast feed (podfeed.ai)`
`image_url`	`string`	optional	Cover image URL for the feed.

Field	Type	Required	Description
`feed`	`object`	optional	Created feed object: { id, name, description, image_url, episode_count, rss_url, created_at }.

List all podcast feeds for the authenticated user.

Field	Type	Required	Description
`feeds`	`array`	optional	Array of feed objects: { id, name, description, image_url, episode_count, rss_url }.

Get feed details including episodes and RSS URL.

Field	Type	Required	Description
`feed_id`	`string`	required	The unique identifier of the feed.

Field	Type	Required	Description
`feed`	`object`	optional	Feed object with episodes: { id, name, description, image_url, episode_count, rss_url, episodes }.

Add a generated audio to a feed as a podcast episode.

Field	Type	Required	Description
`audio_id`	`string`	required	The audio to add as an episode.

Field	Type	Required	Description
`feed_id`	`string`	optional	Target feed ID. If omitted, uses the first feed or creates one.
`episode_title`	`string`	optional	Episode title. Auto-generated as "Episode N" if omitted.

Field	Type	Required	Description
`message`	`string`	optional	Success message.
`episode`	`object`	optional	Created episode object.
`feed_id`	`string`	optional	The feed the episode was added to.

Generate a public share link for an audio.

Field	Type	Required	Description
`audio_id`	`string`	required	The ID of the audio to share.

Field	Type	Required	Description
`url_token`	`string`	optional	Token for accessing the shared audio.

Request signed upload URLs for file-based generation (PDF, audio, video).

Field	Type	Required	Description
`files`	`array`	required	Array of file metadata objects: { filename (string, required), contentType (string), size (integer, required, bytes) }.

Field	Type	Required	Description
`urls`	`array`	optional	Array of upload objects: { filename, signedUrl, gcsUri }. PUT the file to signedUrl, then pass gcsUri to /audios.

Supported Input Types

The generate endpoint accepts these input types. Use content_type="sources" to combine up to 10 inputs in a single request.

url

Website, YouTube video, Apple Podcast, or Spotify episode URL.

text

Plain text or long-form content to convert into audio.

topic

A topic string — the API will research it autonomously before generating.

script

Your own script. Dialogue: alternate HOST:/COHOST: lines. Monologue: plain text.

file

Upload PDF, audio, or video files via signed URLs.

sources

Combine up to 10 URLs, text blocks, and files in one request.

Error Codes

Code	Meaning
`400`	Bad Request — invalid parameters or missing required fields.
`401`	Unauthorized — missing or invalid API key.
`403`	Forbidden — insufficient credits or feature not available on your plan.
`404`	Not Found — the requested resource does not exist.
`429`	Too Many Requests — rate limit exceeded. Retry with exponential backoff.
`500`	Internal Server Error — something went wrong on our end. Retry or contact support.

SDKs & Resources

PythonAvailable

Full-featured Python SDK with Pydantic models, async task polling, file uploads, and comprehensive error handling.

REST

Use the REST API directly from any language. Additional SDK wrappers are planned.

Node.js SDK (coming soon)

Go SDK (coming soon)

PRICING

API Pricing

Credits-based pricing. Same credit model as the UI. Detailed usage tiers coming soon.

Regular

Usage-based with credits

100 credits = $5

Credits-based billing

Same credits as UI version

Standard email support

Planned usage tiers

Enterprise

Volume pricing, SLAs, and custom integrations

Custom

Priority support with dedicated channel

Uptime and response-time SLAs

Dedicated environment/VPC options

Custom integrations and SSO