This guide will show you how to use Python to interact with our Podcast API, specifically how to create a new podcast episode and check its status. For any details about the API, please refer to the API Reference.

​
Prerequisites

  • Python 3.6+
  • requests library (pip install requests)

​
Authentication

You’ll need an API key to authenticate your requests. Replace 'YOUR_API_KEY' in the examples below with your actual API key.

You can get an API key by logging into Wondercraft or creating an account (click “Go to studio” above) if you don’t already have one. Please note, you’ll need to be on a paid plan to access the API.

You can create a new key by clicking on the user avater in the bottom left corner and selecting “API Keys”. There, you will be able to create a new key which you can use to authenticate your requests.

The API key should be passed in the header of your requests as X-API-KEY.

​
Creating a Podcast Episode

To create a new podcast episode, you’ll use the /v1/podcast endpoint with a POST request.

import requests
import json

API_BASE_URL = 'https://api.wondercraft.ai'
API_KEY = 'YOUR_API_KEY'

headers = {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY
}

# Define your episode details
episode_data = {
    "prompt": "Generate a podcast episode covering Sam Altman's post https://ia.samaltman.com/"
}

# Make the POST request to create the episode
response = requests.post(f"{API_BASE_URL}/v1/podcast",
                         headers=headers,
                         data=json.dumps(episode_data))

if response.status_code == 200:
    result = response.json()
    job_id = result['job_id']
    print(f"Episode creation started. Job ID: {job_id}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

​
Checking Episode Status

Once you’ve started the episode creation process, you can check its status using the /v1/podcast/{job_id} endpoint with a GET request.

import requests
import time

API_BASE_URL = 'https://api.wondercraft.ai'
API_KEY = 'YOUR_API_KEY'

headers = {
    'x-api-key': API_KEY
}

def check_episode_status(job_id):
    response = requests.get(f"{API_BASE_URL}/v1/podcast/{job_id}", headers=headers)

    if response.status_code == 200:
        status = response.json()
        return status
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
        return None

# Example usage
job_id = "your_job_id_here"  # Replace with the job_id from the creation response

while True:
    status = check_episode_status(job_id)
    if status and status['finished']:
        print("Episode creation completed!")
        print(f"Download URL: {status['url']}")
        break
    elif status and not status['error']:
        print("Episode creation failed.")
        break
    else:
        print("Episode still processing. Checking again in 10 seconds...")
        time.sleep(10)

This script will check the status every 10 seconds until the episode is either completed or fails.

​
Error Handling

Both endpoints may return a 422 status code for validation errors. Make sure to handle these errors appropriately in your production code.

Additionally, please note that there is currently a limit of 5 concurrent jobs. If you exceed this limit, you will receive a 429 status code.

Introduction