# Advanced Customization Source: https://docs.wondercraft.ai/advanced-usage Start customizing voices and background music via the API This section will guide will show you how to use Python to customize the generated audio with background music and different voices. For any details about the API, please refer to the [API Reference](/api-reference). 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](mailto:support@wondercraft.ai) ## Using your own script 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. ```python theme={null} API_BASE_URL = 'https://api.wondercraft.ai/v1' headers = { 'x-api-key': API_KEY } voice_id_1 = "" 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: ## Adding background music This guide explains how to use the `music_spec` field in the `GenerateAiScriptedEpisodeRequest` to add background music to podcast episodes. The `music_spec` field is an optional component of the requests to `/podcast` and `/podcast/scripted` that allows you to add a background music track to the generated podcast. This field uses the `MusicTrackSpec` model, which provides fine-grained control over the music playback. ### Example music\_spec Configuration Here’s an example of how to use the music\_spec field: ```json theme={null} { "music_spec": { "music_id": "12345", "fade_in_ms": 3000, "fade_out_ms": 2000, "playback_start": 5000, "playback_end": 30000, "volume": 0.05 } } ``` ### Parameters in MusicTrackSpec 1. `music_id` (Required) * Description: The unique ID of the music track to use as background. * Where to find it: Obtain the music\_id from the Wondercraft platform. * Example: "music\_id": "12345" 2. `fade_in_ms` (Optional) * Description: Specifies the duration (in milliseconds) for the music to fade in at the start. * Default: 0 (no fade-in). * Example: `"fade_in_ms": 3000` fades in the music over the first 3 seconds. 3. `fade_out_ms` (Optional) * Description: Specifies the duration (in milliseconds) for the music to fade out at the end. * Default: 0 (no fade-out). * Example: `"fade_out_ms": 2000` fades out the music over the last 2 seconds. 4. `playback_start` (Optional) * Description: The starting point (in milliseconds) of the music track to begin playback. This trims the beginning of the music track. * Default: 0 (play from the beginning). * Example: `"playback_start": 5000` starts the playback 5 seconds into the music track. 5. `playback_end` (Optional) * Description: The point (in milliseconds) at which the music track stops playing. This trims the end of the music track. * Default: Plays until the end of the music track or the length of the generated episode (whichever comes first). * Example: `"playback_end": 30000` stops playback 30 seconds into the music track. 6. `volume` (Optional) * Description: The music playback volume. Must be between 0.0 and 1.0 * Default: 0.05 (or 5%) - For most music tracks, this should be high enough. * Example: `"volume": 0.01` - makes the volume of the music 1% ### Additional Notes 1. Automatic Trimming: The music track is automatically trimmed to match the duration of the generated podcast episode. If the episode is shorter than the music track, playback stops at the episode's end. 2. Music Placement: The music always starts at the beginning of the podcast and cannot be placed at other positions. 3. Dependencies: The music\_spec field is optional. If omitted, no background music will be added. 4. Validation: Ensure the music\_id is valid and that fade\_in\_ms, fade\_out\_ms, playback\_start, and playback\_end are within the bounds of the music track's duration. Example Full Request ```json theme={null} { "prompt": "In this episode, we discuss the future of AI and its impact on the job market.", "voice_ids": ["voice_1", "voice_2"], "music_spec": { "music_id": "c6a490a3-f404-4525-955b-e0baddeafb99", "fade_in_ms": 3000, "fade_out_ms": 2000, "playback_start": 0, "playback_end": 10000, "volume": 0.01 } } ``` This request: * Adds background music with ID "c6a490a3-f404-4525-955b-e0baddeafb99". * Fades in over 3 seconds, starts playback at the beginning of the track, and fades out over 2 seconds. * Stops playback 10 seconds into the music or at the end of the podcast, whichever comes first. * Sets the music volume to 1% # Generate AI-scripted podcast with 2 hosts using Convo Mode Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_ai_scripted POST /podcast/convo-mode/ai-scripted Starts a background job that creates an AI generated script and produces an audio file in convo mode. The response contains a `job_id` that can be used with the `/podcast/{job_id}` endpoint to query for status. Requires a valid `X-API-TOKEN` header. **Note that generating via Convo Mode yields more natural results but takes longer. Expect at least 1 minute of processing per minute duration of audio before investigating a potential failure.** Throws: - 429 if the user has too many jobs in flight. - 400 if any voice_ids provided are invalid or if the length of voice_ids is not 2. # Generate podcast with 2 hosts using Convo Mode, with a user provided script Source: https://docs.wondercraft.ai/api-reference/endpoint/convo_mode_user_scripted POST /podcast/convo-mode/user-scripted Starts a background job to produce an audio file with the provided script segments in convo mode. The response contains a `job_id` that can be used to query with the `/podcast/{job_id}` to query for status. Requires a valid `X-API-TOKEN` header. **Note that generating via Convo Mode yields more natural results but takes longer. Expect at least 1 minute of processing per minute duration of audio before investigating a potential failure.** Throws: - 429 if the user has too many jobs in flight. - 400 if any voice_ids provided are invalid or if the length of voice_ids is not 2. # Create any audio content with an AI-generated script Source: https://docs.wondercraft.ai/api-reference/endpoint/generate_podcast POST /podcast Starts a background job that creates an AI generated script and produces an audio file. The response contains a `job_id` that can be used with the `/podcast/{job_id}` endpoint to query for status. Requires a valid `X-API-TOKEN` header. Throws: - 429 if the user has too many jobs in flight. - 422 if provided voice_ids are not unique - 400 if any voice_ids or music_ids provided are invalid # Get audio content result and status Source: https://docs.wondercraft.ai/api-reference/endpoint/get_job_status GET /podcast/{job_id} Gets the status of podcast generation job, including a link to download it if the job was successful. Requires a valid `X-API-TOKEN` header. The link returned expires after 24 hours. Feel free to call this endpoint again to get a fresh link, no need to regenerate the podcast and waste credits. Throws - 404 if job_id is invalid # Create any audio content with a user provided script Source: https://docs.wondercraft.ai/api-reference/endpoint/user_scripted POST /podcast/scripted Starts a background job to produce an audio file with the provided script segments. The response contains a `job_id` that can be used to query with the `/podcast/{job_id}` to query for status. Requires a valid `X-API-TOKEN` header. Throws: - 429 if the user has too many jobs in flight. - 400 if any voice_id or music_id provided is invalid # Introduction Source: https://docs.wondercraft.ai/api-reference/introduction Discover how to create podcasts, audio ads, meditations and audiobooks using the Wondercraft API. Create an AI-generated podcast with two hosts using Convo Mode, or create an audio ad from prompt to full spec. Visit the [Capabilities](/capabilities) page to get a better understanding of what you can can do using the API. You can expect 1 min of generated audio to cost roughly 10 credits. Otherwise, just head to the [Quickstart](/Quickstart) page to get started. ## Authentication To create audio content, you'll need to get yourself an API key, which you can do by logging into Wondercraft or creating an account 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 navigating to the workspace selector (on the top left of the platform) > Workspace Settings > 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`. ## Base URL The base URL for all requests is `https://api.wondercraft.ai/v1`. ## Rate limits Please note, there is currently a limit of 5 concurrent jobs. If you need to increase this, please contact [support@wondercraft.ai](mailto:support@wondercraft.ai). # Capabilities Source: https://docs.wondercraft.ai/capabilities **The Wondercraft API lets you perform four broad intents:** 1. Create a natural podcast with 2 hosts using Convo Mode, [using AI to generate a script](/api-reference/endpoint/convo_mode_ai_scripted) 2. Create a natural podcast with 2 hosts using Convo Mode, [with a user provided script](/api-reference/endpoint/convo_mode_user_scripted) 3. Create any other audio content (audio ads, podcasts with more or less than 2 speakers, meditations, audiobooks), [using AI to generate a script](/api-reference/endpoint/generate_podcast) 4. Create any other audio content, [with a user provided script](/api-reference/endpoint/user_scripted) **For these actions, the API supports the ability to:** * Choose which voices you want to use * Retrieve the voiceID’s from the studio, including any voice clones and custom voices * Otherwise, default voices will be used * Add music and control its playback *(Not supported by the two Convo Mode podcast endpoints)* * Choose your clip and retrieve the musicID from the studio * Add a fade in and out for a set duration of time * Set when the music playback should start and end * Control the volume of the music clip * Add ‘Delivery Instructions’ prompt on how you want the dialogue to delivered *(Only supported by the two Convo Mode podcast endpoints)* * Specify things like tone, accent, pace, the vibe between the two speakers **The API does not currently support the following capabilities. Please use the Wondercraft Studio to achieve these functionalities:** * Adding sound effects * Performing timeline controls on voice, such as speed, splitting, trimming, adding or removing pauses, volume and duplication * Uploading your own audio clips and music * Iteratively editing from a draft or starting point # Introduction Source: https://docs.wondercraft.ai/introduction Generate any audio content via API Hero Light Hero Dark ## Welcome Discover how to create podcasts, audio ads, meditations and audiobooks using the Wondercraft API. Create an AI-generated podcast with two hosts using Convo Mode, or create an audio ad from prompt to full spec. Visit the [Capabilities](/capabilities) page to get a better understanding of what you can can do using the API. You can expect 1 min of generated audio to cost roughly 10 credits. Otherwise, just head to the Quickstart page to get started. # Quickstart Source: https://docs.wondercraft.ai/quickstart Generate any audio content via API 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](/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 navigating to the workspace selector (on the top left of the platform) > Workspace Settings > 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. ```python theme={null} 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. ```python theme={null} 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](/api-reference/endpoint/get_job_status) 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](mailto: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. ```python theme={null} API_BASE_URL = 'https://api.wondercraft.ai/v1' headers = { 'x-api-key': API_KEY } voice_id_1 = "" 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: