> ## 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.
# Introduction to segments
## Segments
Each content item can have multiple segments. For instance, an article typically includes a title, a summary and a body. The body itself typically contains multiple paragraphs, which may include multimedia elements such as images, audio clips, and videos. These individual components are referred to as segments. Segmenting content enables flexibility, allowing for a range of features when combined with the [BeyondWords Player](https://github.com/beyondwords-io/player). These include skipping between segments, initiating playback from specific segments (e.g., clicking play on a paragraph), and highlighting segments during playback (e.g., paragraph highlighting as it plays).
You have three options when it comes to generating audio: `auto_segment`, `manual_segment`, or `audio_upload`.
### auto\_segment
We recommend the `auto_segment` option for publishers seeking a simple way to generate audio versions of their articles.
To use this option set `type` property to `auto_segment` whenever you create or update a content item.
Using this option, you are required to submit data for the `body` property, with the `title` and `summary` properties being optional additions.
Once submitted, BeyondWords will automatically segment the `body` data into `segments`. In the initial response, the `segments` will be an empty array, as automatic segmenting is an asynchronous operation. However, once the audio has been generated and you retrieve a content item using the `?segments=full` query parameter, you will be able to view the individual segments.
**Example request and responses:**
```json Example POST request theme={null}
{
"type": "auto_segment",
"title": "
The policy is designed to reduce emissions. In practice, it may do the opposite.
```
The pause value is a number in seconds (max 3), with up to one decimal place. You can optionally include an `s` suffix (for example, `3s`, `1.2s`, `1`, or `2.4`).
### manual\_segment
We recommend the `manual_segment` option for publishers seeking enhanced control over the audio conversion of their content. This is particularly beneficial for those who wish to integrate the content API into their editorial interface or create videos with multiple images (coming soon).
To use this option set `type` property to `manual_segment` whenever you create or update a content item.
Using this option, you **should not** submit any data to the `title`, `body` or `summary` properties.
Instead, you will need to submit an array of one or multiple `segments`.
For each segment you submit you will need to submit data to the following properties:
| Property | Options |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `section` | Use this property define the section type of a segment as either `title`, `summary` or `body`. |
| `content_type` | If `content_type` is `text` then submit plain text to be converted into audio. If no `voice_id` is submitted then the audio will be generated with the default project voices assigned title, summary or body in the project. |
| | If `content_type` is `audio` then submit an `audio_url` to be uploaded. |
| | If `content_type` is `image` then submit an `image_url` to be uploaded. |
Once submitted, BeyondWords will generate the audio for segments with text and then concatenate all segments into a single audio.
Text and audio will be included in generated audios and text, audio and images will be included in generated videos.
**Example request and responses:**
```json Example POST request theme={null}
{
"type": "manual_segment",
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"segments": [
{
"section": "title",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is a title",
"voice": {
"id": 1
}
},
{
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a2",
"content_type": "text",
"text": "This is a paragraph",
"voice": {
"id": 1
}
},
{
"section": "body",
"content_type": "image",
"image_url": "https://example.com/image.jpeg"
},
{
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6311a5",
"content_type": "text",
"text": "This is another paragraph",
"voice": {
"id": 1
}
},
{
"section": "body",
"marker": "75aa616c-1849-4d71-bb3b-7691cc6310a5",
"content_type": "audio",
"audio_url": "https://example.com/audio.mp3"
},
{
"section": "body",
"marker": "75aa416c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is another paragraph",
"voice": {
"id": 1
}
}
],
"published": true,
"ads_enabled": false,
"auto_segment_updates_enabled": false
}
```
```json Example GET response theme={null}
{
"id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
"status": "processed",
"type": "manual_segment",
"title": null,
"summary": null,
"body": null,
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Steve Jobs",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"audio": [
{
"id": 1,
"content_type": "application/vnd.apple.mpegurl",
"url": "https://example.com/audio.m3u8",
"duration": 10000
},
{
"id": 2,
"content_type": "audio/mpeg,",
"url": "https://example.com/audio.mp3",
"duration": 10000
}
],
"video": [],
"segments": [
{
"id": 1,
"section": "title",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is a title",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 2,
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6310a2",
"content_type": "text",
"text": "This is a paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 3,
"section": "body",
"content_type": "image",
"text": null,
"audio_url": null,
"image_url": "https://example.com/image.jpeg",
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 4,
"section": "body",
"marker": "75aa616c-1849-4d70-bb3b-7691cc6311a5",
"content_type": "text",
"text": "This is another paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 5,
"section": "body",
"marker": "75aa616c-1849-4d71-bb3b-7691cc6310a5",
"content_type": "audio",
"text": null,
"audio_url": "https://example.com/image.mp3",
"image_url": null,
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
},
{
"id": 6,
"section": "body",
"marker": "75aa416c-1849-4d70-bb3b-7691cc6310a5",
"content_type": "text",
"text": "This is another paragraph",
"audio_url": null,
"image_url": null,
"language": {
"code": "en_US",
"name": "English"
},
"voice": {
"id": 123,
"name": "Steve"
},
"start_time": 3,
"duration": 2000,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
}
],
"ads_enabled": true,
"auto_segment_updates_enabled": true,
"created": "2023-01-01T00:00:00Z",
"updated": "2023-01-01T00:00:05Z"
}
```
You can optionally define verbal pauses in text using the BeyondWords-native pause tag:
```html theme={null}
```
For example:
```text theme={null}
The policy is designed to reduce emissions. In practice, it may do the opposite.
```
The pause value is a number in seconds (max 3), with up to one decimal place. You can optionally include an `s` suffix (for example, `3s`, `1.2s`, `1`, or `2.4`).
### audio\_upload
We recommend `audio_upload` option for publishers that want to host podcasts or human-recorded articles on BeyondWords and leverage the BeyondWords Player, podcast feeds and analytics.
To use this option set the `type` property to `audio_upload` whenever you create or update a content item.
Using this option, you should submit a `title`, `body` and `segments` array with a single segment object with `section` set to `title`, `content_type` set to `audio` and an `audio_url` with a URL to the audio file to be upload.
The title and body text will not be converted into audio. However the text may be present in the player or podcast feeds depending on your player or playlist settings.
**Example request:**
```json Example POST request theme={null}
{
"type": "audio_upload",
"title": "Podcast episode title",
"body": "Podcast episode description",
"source_id": "example-source-id",
"source_url": "https://example.com/some-article",
"author": "Harry Stebbings",
"image_url": "https://example.com/image.jpeg",
"metadata": {
"key": "value"
},
"segments": [
{
"section": "title",
"content_type": "audio",
"audio_url": "https://example.com/audio.mp3"
}
],
"published": true,
"ads_enabled": true,
"auto_segment_updates_enabled": false
}
```