API v1 Documentation — View changelog
Vozia
POST /api/v1/podcasts

Create Podcast

Submit your content and get back a podcast ID. The AI will analyze your content and write a two-person conversation script.

Minimal Example

Only 2 fields are required when using API key authentication. This is the simplest request you can make:

Minimum required fields
{
  "title": "My First Podcast",
  "content": [
    {
      "type": "text",
      "value": "Your article or content goes here..."
    }
  ]
}

Note: When using an API key, your organizationId is automatically inferred from the key. No need to include it in the request body.

Required Parameters must include

title string

A name for your podcast (1-200 characters).

Example: "The Future of AI in 2024"
content array

The source material for your podcast. This is what the AI will turn into a conversation.

Option 1: Plain text

Paste an article, blog post, or any text directly.

Text content
{
  "content": [
    {
      "type": "text",
      "value": "Paste your article, blog post, or any text here..."
    }
  ]
}
Option 2: URL to a document

Link to a PDF, webpage, or document. We'll fetch and process it.

URL content
{
  "content": [
    {
      "type": "url",
      "value": "https://example.com/article.pdf"
    }
  ]
}
Option 3: Mix multiple sources

Combine text and URLs for richer content.

Mixed content
{
  "content": [
    { "type": "text", "value": "Introduction paragraph..." },
    { "type": "url", "value": "https://example.com/research.pdf" },
    { "type": "text", "value": "Additional context..." }
  ]
}

Optional Parameters defaults provided

style string · default: "conversational"

How the two speakers should interact:

conversational

Casual, friendly chat (default)

interview

Q&A format, one asks questions

educational

Teaching tone, explains concepts

debate

Different viewpoints discussed

storytelling

Narrative-driven, story format

Example
{
  "style": "interview"
}
targetDuration number · default: 5

How long the podcast should be, in minutes (1-60).

10 minute podcast
{
  "targetDuration": 10
}
speakers object

Customize the two voices. By default, uses Alex (male host) and Olivia (female guest). See available voices.

Speakers config
{
  "speakers": {
    "host": {
      "voice": "Alex",
      "displayName": "Dr. Smith"
    },
    "guest": {
      "voice": "Olivia",
      "displayName": "AI Expert"
    }
  }
}
description string · optional

A short description of the podcast (for your reference).

language string · default: "en"

Language code for the podcast (e.g., "en", "es", "fr").

Example: "en"
model string · default: "inworld-tts-1.5-mini"

Which voice synthesis model to use:

inworld-tts-1.5-mini Fastest, efficient (default)
inworld-tts-1.5 Standard quality
inworld-tts-1.5-max Premium quality
format string · default: "mp3"

Audio output format:

mp3 Compressed (default)
wav Uncompressed

Full Example (with optional fields)

Here's a request using most available options:

JSON
{
  "title": "AI in Healthcare",
  "description": "A discussion about AI transforming healthcare",
  "content": [
    {
      "type": "text",
      "value": "Artificial intelligence is revolutionizing healthcare..."
    }
  ],
  "speakers": {
    "host": { "voice": "Alex", "displayName": "Dr. Smith" },
    "guest": { "voice": "Olivia", "displayName": "AI Expert" }
  },
  "style": "interview",
  "targetDuration": 10,
  "language": "en",
  "model": "inworld-tts-1.5-mini",
  "format": "mp3"
}

Response

You get back the podcast details including ID, status, and audio URL. The status starts as draft.

201 Created
Response
{
  "id": "pod_xyz789",
  "title": "AI in Healthcare",
  "description": "A discussion about AI transforming healthcare",
  "status": "draft",
  "speakers": {
    "host": { "voice": "Alex", "displayName": "Dr. Smith" },
    "guest": { "voice": "Olivia", "displayName": "AI Expert" }
  },
  "style": "interview",
  "targetDuration": 10,
  "audioUrl": "https://res.cloudinary.com/vozia/podcasts/pod_xyz789.mp3",
  "createdAt": "2024-01-15T10: 30: 00Z"
}

Code Examples

JavaScript
const response = await fetch(class="hl-string">'https://vozia.renbo.site/v1/podcasts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'AI in Healthcare',
    content: [
      { type: 'text', value: 'Your content here...' }
    ]
  })
});

const podcast = await response.json();
console.log('Podcast ID:', podcast.id);
// Next: call POST /podcasts/{id}/generate to start
cURL
curl -X POST https://vozia.renbo.site/v1/podcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI in Healthcare",
    "content": [{ "type": "text", "value": "Your content..." }]
  }'

Common Errors

400 Missing required field

Make sure you include organizationId, title, and content.

400 Content is empty

The content array must have at least one item with a non-empty value.

401 Invalid API key

Check your Authorization header. Key should start with vz_live_ or vz_test_.

Next Step: Generate Audio

Creating the podcast only saves the content and writes the script. To actually generate the audio file, call the generate endpoint with your podcast ID.

Generate Audio → Browse Voices