> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace audio

> Replace AI-generated audio with an uploaded audio file

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.

<Tip>
  To replace audio through the dashboard instead, go to **Content → Items**, click **••• → Replace** alongside the item, and follow the steps in [Upload audio](/docs-and-guides/tools/upload-audio#replace-an-existing-content-item).
</Tip>

## Replace audio on an existing content item

To replace audio on an existing content item, send a `PUT` request to [Update content](/api-reference/content/update) 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.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

## 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"`:

```json theme={null}
{
  "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](/api-reference/content/processing-types#audio_upload) 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](/api-reference/content/upload) to upload it to BeyondWords storage first. That endpoint returns a URL you can then pass as `audio_url`.