Processing types

The type property on a content item determines how BeyondWords processes it. Set type when you create or update an item.

auto_segment

Recommended for most publishers. Submit HTML for body (and optionally title and summary). BeyondWords segments the body automatically and generates audio asynchronously.

{
  "type": "auto_segment",
  "title": "<h1>Article title</h1>",
  "summary": "<h2>Summary</h2>",
  "body": "<p>First paragraph.</p><p>Second paragraph.</p>",
  "source_id": "cms-article-123",
  "source_url": "https://example.com/article",
  "published": true
}

The initial response returns status: "queued" and an empty segments array. After processing, call Get content with ?segments=full to retrieve segment markers and timings.

Pause markers

Add verbal pauses in HTML:

<p>The policy reduces emissions. <span data-beyondwords-pause="1.0"></span> In practice, it may do the opposite.</p>

Pause values are in seconds (max 3), with up to one decimal place.

manual_segment

For editorial tools or fine-grained control. Do not send title, summary, or body. Instead, send a segments array.

Property	Options
`section`	`title`, `summary`, or `body`
`content_type`	`text` (TTS), `audio` (upload URL), or `image` (for video)

{
  "type": "manual_segment",
  "source_id": "cms-article-123",
  "segments": [
    { "section": "title", "content_type": "text", "text": "Article title" },
    { "section": "body", "content_type": "text", "text": "First paragraph.", "marker": "para-1" },
    { "section": "body", "content_type": "text", "text": "Second paragraph.", "marker": "para-2" }
  ]
}

Use marker on text segments when you need segment-level playback in the player. For pauses in plain text, use <pause time="1.0s" />.

audio_upload

For podcasts or pre-recorded audio. Submit a title, body (shown in the player or feeds as metadata), and one audio segment:

{
  "type": "audio_upload",
  "title": "Episode title",
  "body": "Episode description",
  "source_id": "episode-42",
  "segments": [
    { "section": "title", "content_type": "audio", "audio_url": "https://example.com/episode.mp3" }
  ],
  "published": true
}

The title and body are not converted to speech. Use Upload file if you need to upload the audio file to BeyondWords first. To replace AI-generated audio on an existing item, see Replace audio.

Choosing a type

Type	Best for
`auto_segment`	CMS integrations, article-to-audio pipelines
`manual_segment`	Custom editorial UIs, mixed media, precise segment control
`audio_upload`	Podcasts, human-recorded narration

Getting started

Content

Extraction

Pronunciation settings

Script settings

Video settings

Background music settings

Voices

Distribution

Integrations

Analytics

Monetization

Organization

auto_segment

Pause markers

manual_segment

audio_upload

Choosing a type

​auto_segment

​Pause markers

​manual_segment

​audio_upload

​Choosing a type

auto_segment

Pause markers

manual_segment

audio_upload

Choosing a type