API v1 Documentation — View changelog
Vozia

Quick Start

Create your first AI-generated podcast in just a few steps. This guide shows you the complete workflow.

What you'll create

By the end of this guide, you'll have a working MP3 podcast file — a two-person conversation generated from your text content. The AI writes the script and synthesizes realistic voices automatically.

Before you start

  • A Vozia account (sign up free)
  • An API key from the Dashboard (Settings → API Keys)
  • Node.js 18+ or Python 3.8+ (optional — you can also use cURL)
1

Install the SDK (Optional)

The SDK makes things easier, but you can also use plain HTTP requests with cURL or fetch.

JavaScript
npm install @vozia/sdk
Python
pip install vozia
2

Create a Podcast

This call does two things: (1) stores your content, and (2) uses AI to write a two-person podcast script. You get back a podcast.id to use in the next steps.

JavaScript
import { Vozia } from class="hl-string">'@vozia/sdk';

const vozia = new Vozia({ apiKey: class="hl-string">'vz_live_xxx' });

class="hl-comment">// Create a podcast from text content
const podcast = await vozia.podcasts.create({
  organizationId: class="hl-string">'org_xxx',
  title: class="hl-string">'My First Podcast',
  content: [
    {
      type: class="hl-string">'text',
      value: class="hl-string">`
        Artificial Intelligence is transforming every industry.
        From healthcare to finance, AI is making processes faster
        and more efficient. Let's explore the key trends...
      `
    }
  ],
  style: class="hl-string">'conversational',
  targetDuration: 5  class="hl-comment">// 5 minutes
});

console.log(class="hl-string">'Podcast created:', podcast.id);

Key parameters: content is your source material (text, URL, or file). style controls the tone (conversational, interview, educational). targetDuration sets length in minutes.

3

Generate Audio

Now trigger the actual audio synthesis. This is a separate step because generation can take 30 seconds to a few minutes depending on length.

JavaScript
class="hl-comment">// Start generation
const job = await vozia.podcasts.generate(podcast.id);

console.log(class="hl-string">'Generation started:', job.jobId);
class="hl-comment">// job.status = class="hl-string">'queued'

Important: This returns immediately with status queued. The audio is being generated in the background — you need to poll for completion (next step).

4

Check Status & Get Audio

Poll the status endpoint every few seconds. When status becomes ready, the audioUrl will contain your MP3 file.

JavaScript
class="hl-comment">// Poll for completion
async function waitForCompletion(podcastId) {
  while (true) {
    const status = await vozia.podcasts.status(podcastId);

    console.log(class="hl-string">`Progress: ${status.job?.progress}%`);

    if (status.status === class="hl-string">'ready') {
      console.log(class="hl-string">'Audio URL:', status.audioUrl);
      console.log(class="hl-string">'Duration:', status.duration, class="hl-string">'seconds');
      return status;
    }

    if (status.status === class="hl-string">'failed') {
      throw new Error(status.errorMessage);
    }

    class="hl-comment">// Wait 2 seconds before checking again
    await new Promise(r => setTimeout(r, 2000));
  }
}

const result = await waitForCompletion(podcast.id);

Status values: queued → processing → ready (or failed)

Complete Example

Here's everything together — copy this file, add your API key, and run it to create a podcast.

create-podcast.js
import { Vozia } from class="hl-string">'@vozia/sdk';

async function createPodcast() {
  const vozia = new Vozia({ apiKey: process.env.VOZIA_API_KEY });

  class="hl-comment">// 1. Create podcast
  const podcast = await vozia.podcasts.create({
    organizationId: class="hl-string">'org_xxx',
    title: class="hl-string">'AI Trends 2024',
    content: [
      { type: class="hl-string">'text', value: class="hl-string">'Your content here...' }
    ],
    speakers: {
      host: { voice: class="hl-string">'Alex', displayName: class="hl-string">'Alex' },
      guest: { voice: class="hl-string">'Olivia', displayName: class="hl-string">'Dr. Smith' }
    },
    style: class="hl-string">'interview',
    targetDuration: 10
  });

  class="hl-comment">// 2. Start generation
  await vozia.podcasts.generate(podcast.id);

  class="hl-comment">// 3. Wait for completion
  let status;
  do {
    await new Promise(r => setTimeout(r, 3000));
    status = await vozia.podcasts.status(podcast.id);
    console.log(class="hl-string">`Status: ${status.status}, Progress: ${status.job?.progress}%`);
  } while (status.status !== class="hl-string">'ready' && status.status !== class="hl-string">'failed');

  if (status.status === class="hl-string">'ready') {
    console.log(class="hl-string">'[OK] Podcast ready!');
    console.log(class="hl-string">'Audio:', status.audioUrl);
    console.log(class="hl-string">'Duration:', Math.round(status.duration / 60), class="hl-string">'minutes');
  } else {
    console.error(class="hl-string">'[ERROR] Failed:', status.errorMessage);
  }
}

createPodcast();

Common Issues

401 Unauthorized

Check that your API key is correct and starts with vz_live_ or vz_test_

Status stuck on "processing"

Long podcasts can take several minutes. Keep polling — there's no timeout on our end.

Status is "failed"

Check errorMessage in the response. Common causes: empty content, unsupported file type.

What's Next?

Now that you've created your first podcast, explore more features:

Choose Different Voices

12 voices with different genders and styles
Write Your Own Script

Skip AI generation, provide exact dialogue
Full API Reference

All parameters and options explained
Authentication Details

API keys, test vs production, security