This guide will show you how to use Python to interact with our API, specifically how to create any audio content 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 Audio Content

To create a new podcast episode, you’ll use the /podcast endpoint with a POST request. Wondercraft AI will start a job that will generate a script for your podcast based on the provided prompt. 
import requests
import json

API_BASE_URL = 'https://api.wondercraft.ai/v1'
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}/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 /podcast/{job_id} endpoint with a GET request. 
import requests
import time

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

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

def check_episode_status(job_id):
    response = requests.get(f"{API_BASE_URL}/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 status['error'] == True:
        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. If the job completed successfully, the response will include a URL to download the generated mp3 file. Check API Docs for more details on the shape of the response.

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

​
Advanced Customization

This API is under rapid development. We are working hard to improve existing functionality and add missing functionality and as such might need to drop support for existing workflows. If you have any feature requests or concerns, please contact support@wondercraft.ai
If you would prefer to provide your own script, you can use the /podcast/scripted endpoint instead. The payload for that request looks slightly different. You will provide script segemnts, where each segment contains the text and the voice id for the speaker. 
API_BASE_URL = 'https://api.wondercraft.ai/v1'
headers = {
    'x-api-key': API_KEY
}

voice_id_1 = "<voice_id_1>"
voice_id_2 = "<voice_id_2>"

script_payload = {
    "script": [
        {"text": "This is the first speaker", "voice_id": voice_id_1},
        {"text": "And this the second speaker", "voice_id": voice_id_2},
        {"text": "This is the first speaker again", "voice_id": voice_id_1},
        {"text": "The first speaker likes to talk alot", "voice_id": voice_id_2},
        {"text": "ha ha ha... ok I do", "voice_id": voice_id_1},
    ]
}

response = requests.post(API_BASE_URL + "/podcast/scripted", json=script_payload, headers=headers)
Voice IDs can be copied from the Wondercraft platform: