Items

Update content

Updates a content item in your project.

Segment replace semantics: When you include a segments array, it becomes the new complete set of segments. Segments with an id are kept or updated; segments without an id are added; segments omitted from the array are deleted.

Regeneration: Only changed segments are re-synthesized — unchanged segment audio is reused. A PUT that changes segments triggers regeneration automatically. Use POST /content/{id}/regenerate only when you need to regenerate without segment changes (for example, after updating voice or preprocessing settings).

PUT

projects

{project_id}

content

{id}

curl --request PUT \
  --url https://api.beyondwords.io/v1/projects/{project_id}/content/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "title": "<h1 data-beyondwords-marker=\"h1-title\">Example title</h1>",
  "summary": "<h2 data-beyondwords-marker=\"h2-summary\">This article is about TTS</h2>",
  "body": "<p data-beyondwords-marker=\"paragraph-1\">Example body</p>",
  "summary_enabled": false,
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "John Smith",
  "image_url": "https://example.com/image.jpeg",
  "metadata": {
    "key": "value"
  },
  "published": true,
  "publish_date": "2023-01-01 00:00:00 UTC",
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "generate_audio": true,
  "title_voice_id": 1,
  "summary_voice_id": 1,
  "body_voice_id": 1
}
'

{
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "status": "processed",
  "type": "auto_segment",
  "title": "<h1 data-beyondwords-marker=\"h1-title\">Example title</h1>",
  "summary": "<h2 data-beyondwords-marker=\"h2-summary\">This article is about TTS</h2>",
  "body": "<p data-beyondwords-marker=\"paragraph-1\">Example body</p>",
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "John Smith",
  "image_url": "https://example.com/image.jpeg",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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": [
    {
      "id": 1,
      "content_type": "video/mp4",
      "url": "https://example.com/waveform-video.mp4",
      "duration": 10000
    }
  ],
  "segments": [
    {
      "id": 1,
      "section": "title",
      "marker": "h1-title",
      "xpath": "/html/body/h1",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "Example title",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": {
        "ai_preprocessing_enabled": true
      },
      "start_time": 3,
      "duration": 2000,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    },
    {
      "id": 2,
      "section": "summary",
      "marker": "h2-summary",
      "xpath": "/html/body/h2",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "This article is about text-to-speech",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": null,
      "start_time": 2006,
      "duration": 6000,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    },
    {
      "id": 3,
      "section": "body",
      "marker": "paragraph-1",
      "xpath": "/html/body/p[1]",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "Example title",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": null,
      "start_time": 8009,
      "duration": 1991,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    }
  ],
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "generate_audio": true,
  "created": "2023-01-01 00:00:00 UTC",
  "updated": "2023-01-01 00:00:05 UTC"
}

Authorizations

X-Api-Key

string

header

required

Path Parameters

project_id

string

required

The numeric ID of your project

string

required

The content item's identifier, one of: UUID, source ID, legacy ID

Query Parameters

segments

string

The level of detail to show for segments in the response: 'none', 'partial' or 'full'

Body

application/json

Auto segment
Manual segment
Audio upload

Update content with auto segment type

title

string | null

The content title

summary

string | null

The content summary

body

string | null

The content body

title_enabled

boolean

The flag to enable title segments in audio

body_enabled

boolean

The flag to enable body segments in audio

summary_enabled

boolean

The flag to enable summary audio

summary_title_enabled

boolean

The flag to include title text and audio segments in summaries

source_id

string | null

The externally-provided source identifier of the content

source_url

string | null

The URL that contains the source content

author

string | null

The author of the content

Response

200 - application/json

successful

string | null

Unique identifier for the content. Can be either a UUID or an externally provided source_id

status

enum<string>

The current status of the content processing operation. This value will change as the content is processed. ready means the content is prepared and indexed, but audio generation wasn't requested (generate_audio is false). Reaching ready sends a content.ready webhook with the ready state and without media, a preparation failure sends audio.error.

Available options:

draft,

ready,

queued,

processing,

processed,

skipped,

error

type

enum<string>

The content type. Possible values are auto_segment, manual_segment or audio_upload

Available options:

auto_segment,

manual_segment,

audio_upload

title

string | null

The content title

Required string length: 1 - 500

summary

string | null

The content summary

Maximum string length: 2000

body

string | null

The content body

Maximum string length: 100000

title_enabled

boolean

The flag to enable title segments in audio

body_enabled

boolean

The flag to enable body segments in audio

summary_enabled

boolean

The flag to enable summary audio

summary_title_enabled

boolean

The flag to include title text and audio segments in summaries

source_id

string | null

The externally-provided source identifier of the content

source_url

string | null

The URL that contains the source content

author

string | null

The author of the content

tags

string[]

Arbitrary tags associated with the content, used for playlist filtering

image_url

string | null

deprecated

The feature image URL of the content

metadata

object | null

deprecated

The arbitrary metadata associated with content

audio

object[]

The array of audio files for the entire content

Show child attributes

video

object[]

The array of video files for the entire content

Show child attributes

audio_with_intro_outro

object[]

Show child attributes

summarization

object

Show child attributes

segments

object[] | null

The array of segments in the content

Show child attributes

published

boolean

Whether the content will appear in the BeyondWords players and podcast feeds

video_published

boolean

Whether the content will appear in the BeyondWords video players and podcast video feeds

publish_date

string | null

Time at which the content was published or is scheduled to be published (ISO 8601)

ads_enabled

boolean

Whether adverts will play for this content in the BeyondWords players

ai_summary_prompt

string | null

The last used AI prompt for summary generation

Maximum string length: 1000

ai_summary_updates_enabled

boolean

Whether the summary segments will be regenerated when the text content is updated

auto_segment_updates_enabled

boolean

Whether the media files will be regenerated when the text content is updated with auto_segment. Content with generate_audio set to false is always prepared and indexed again on text updates

generate_audio

boolean

Whether audio (and dependent video) is generated automatically for the content. Content with false is prepared and indexed without audio generation and has the ready status unless it already has audio. Not applicable to audio_upload content

background_track

object | null

Show child attributes

feature_image

object | null

Show child attributes

feature_video

object | null

Show child attributes

summarization_settings

object | null

Show child attributes

video_settings

object | null

Show child attributes

preprocessing_settings

object | null

Show child attributes

language

string | null

The default language of the content

created

string<date-time>

Time at which the object was created (ISO 8601)

updated

string<date-time>

Time at which the object was updated (ISO 8601)

curl --request PUT \
  --url https://api.beyondwords.io/v1/projects/{project_id}/content/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "title": "<h1 data-beyondwords-marker=\"h1-title\">Example title</h1>",
  "summary": "<h2 data-beyondwords-marker=\"h2-summary\">This article is about TTS</h2>",
  "body": "<p data-beyondwords-marker=\"paragraph-1\">Example body</p>",
  "summary_enabled": false,
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "John Smith",
  "image_url": "https://example.com/image.jpeg",
  "metadata": {
    "key": "value"
  },
  "published": true,
  "publish_date": "2023-01-01 00:00:00 UTC",
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "generate_audio": true,
  "title_voice_id": 1,
  "summary_voice_id": 1,
  "body_voice_id": 1
}
'

{
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "status": "processed",
  "type": "auto_segment",
  "title": "<h1 data-beyondwords-marker=\"h1-title\">Example title</h1>",
  "summary": "<h2 data-beyondwords-marker=\"h2-summary\">This article is about TTS</h2>",
  "body": "<p data-beyondwords-marker=\"paragraph-1\">Example body</p>",
  "source_id": "example-source-id",
  "source_url": "https://example.com/some-article",
  "author": "John Smith",
  "image_url": "https://example.com/image.jpeg",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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": [
    {
      "id": 1,
      "content_type": "video/mp4",
      "url": "https://example.com/waveform-video.mp4",
      "duration": 10000
    }
  ],
  "segments": [
    {
      "id": 1,
      "section": "title",
      "marker": "h1-title",
      "xpath": "/html/body/h1",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "Example title",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": {
        "ai_preprocessing_enabled": true
      },
      "start_time": 3,
      "duration": 2000,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    },
    {
      "id": 2,
      "section": "summary",
      "marker": "h2-summary",
      "xpath": "/html/body/h2",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "This article is about text-to-speech",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": null,
      "start_time": 2006,
      "duration": 6000,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    },
    {
      "id": 3,
      "section": "body",
      "marker": "paragraph-1",
      "xpath": "/html/body/p[1]",
      "md5": "0cc175b9c0f1b6a831c399e269772661",
      "content_type": "text",
      "text": "Example title",
      "audio_url": null,
      "image_url": null,
      "language": {
        "code": "en_GB",
        "name": "English"
      },
      "voice": {
        "id": 123,
        "name": "Jane"
      },
      "preprocessing_settings": null,
      "start_time": 8009,
      "duration": 1991,
      "created": "2023-01-01 00:00:00 UTC",
      "updated": "2023-01-01 00:00:05 UTC"
    }
  ],
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "generate_audio": true,
  "created": "2023-01-01 00:00:00 UTC",
  "updated": "2023-01-01 00:00:05 UTC"
}

Getting started

Content

Extraction

Pronunciation settings

Summary settings

Video settings

Background music settings

Voices

Distribution

Integrations

Analytics

Monetization

Organization

Update content

Authorizations

Path Parameters

Query Parameters

Body

Response