Skip to main content
You can use the API to replace the AI-generated audio on an existing content item with your own audio file. This is useful if you want to switch to a human-recorded version while keeping the same content item, player embeds, distributions, and analytics intact. The same workflow applies whether you’re replacing a single item or doing it in bulk.
To replace audio through the dashboard instead, go to Content → Items, click ••• → Replace alongside the item, and follow the steps in Upload audio.

​
Replace audio on an existing content item

To replace audio on an existing content item, send a PUT request to Update content with "type": "audio_upload". This switches the content item’s processing type and replaces its audio with the file you provide. The audio_url must be a publicly accessible URL. BeyondWords fetches the file from that URL when it processes the request — the file is not uploaded directly in the request body. 
{
  "type": "audio_upload",
  "auto_segment_updates_enabled": false,
  "segments": [
    {
      "section": "title",
      "content_type": "audio",
      "audio_url": "https://example.com/your-replacement-audio.mp3"
    }
  ]
}
The {id} path parameter accepts either the content UUID or the original source_id you set when creating the item.
Set "auto_segment_updates_enabled": false to prevent future text edits from triggering AI regeneration and overwriting your uploaded audio. Without this, editing the title, summary, or body of the item will queue a new AI generation run.

​
Create a new content item with uploaded audio

If you’re creating a new content item from scratch with an audio file rather than replacing an existing one, use POST /projects/{project_id}/content with "type": "audio_upload": 
{
  "type": "audio_upload",
  "title": "My article title",
  "body": "Article body text",
  "source_id": "your-cms-article-id",
  "published": true,
  "segments": [
    {
      "section": "title",
      "content_type": "audio",
      "audio_url": "https://example.com/your-audio-file.mp3"
    }
  ]
}
See Processing types for more on the audio_upload type.

​
Upload a file to BeyondWords first

If your audio file isn’t already hosted at a public URL, use Upload file to upload it to BeyondWords storage first. That endpoint returns a URL you can then pass as audio_url.