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 3 fields are required. 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..."
    }
  ]
}

Required Parameters must include

organizationId string

Your organization ID. Find this in Dashboard → Settings.

Example: "org_abc123"
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

interview

Q&A format, one asks questions

educational

Teaching tone, explains concepts

debate

Different viewpoints discussed

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).

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

Which voice synthesis model to use:

inworld-tts-1.5-mini Fastest, efficient
inworld-tts-1.5 Standard quality
inworld-tts-1.5-max Premium quality

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,
  "model": "inworld-tts-1.5-mini"
}

Response

You get back the podcast ID and status. The status starts as draft.

201 Created
Response
{
  "id": "pod_xyz789",
  "title": "AI in Healthcare",
  "status": "draft",
  "createdAt": "2024-01-15T10: 30: 00Z"
}

Code Examples

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

const podcast = await response.json();
console.log(class="hl-string">'Podcast ID:', podcast.id);
class="hl-comment">// Next: call POST /podcasts/{id}/generate to start
cURL
curl -X POST https://api.vozia.io/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