> ## 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.
# Update content
> Update a content item from your project
## OpenAPI
````yaml put /projects/{project_id}/content/{id}
openapi: 3.0.1
info:
title: BeyondWords REST API
description: |-
This is the documentation for the BeyondWords REST API.
You can use this API to use BeyondWords programmatically.
You can get your API Key and Project ID for each project in the Project settings tab in the BeyondWords
dashboard.
version: 1.0.0
servers:
- url: https://api.beyondwords.io/v1
security: []
paths:
/projects/{project_id}/content/{id}:
parameters:
- name: project_id
in: path
description: The numeric ID of your project
required: true
schema:
type: string
- name: id
in: path
description: 'The content item''s identifier, one of: UUID, source ID, legacy ID'
required: true
schema:
type: string
put:
tags:
- Content
summary: Update
description: Update a content item from your project
operationId: content#update
parameters:
- name: segments
in: query
description: >-
The level of detail to show for segments in the response: 'none',
'partial' or 'full'
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/requestBodyContentUpdateAutoSegment'
- $ref: '#/components/schemas/requestBodyContentUpdateManualSegment'
- $ref: '#/components/schemas/requestBodyContentUpdateAudioUpload'
examples:
example_auto_segment:
$ref: >-
#/components/examples/requestBodyUpdateAutoSegmentContentRequestExample
example_manual_segment:
$ref: >-
#/components/examples/requestBodyUpdateManualSegmentContentRequestExample
example_audio_upload:
$ref: >-
#/components/examples/requestBodyUpdateAudioUploadContentRequestExample
responses:
'200':
description: successful
content:
application/json:
examples:
example:
$ref: '#/components/examples/contentExample'
schema:
$ref: '#/components/schemas/contentModel'
security:
- apiKey: []
components:
schemas:
requestBodyContentUpdateAutoSegment:
title: Auto segment
description: Update content with auto segment type
type: object
properties:
title:
type: string
description: The content title
nullable: true
summary:
type: string
description: The content summary
nullable: true
body:
type: string
description: The content body
nullable: true
title_enabled:
type: boolean
description: The flag to enable title segments in audio
body_enabled:
type: boolean
description: The flag to enable body segments in audio
summary_enabled:
type: boolean
description: The flag to enable summary audio
summary_title_enabled:
type: boolean
description: The flag to include title text and audio segments in summaries
source_id:
type: string
description: The externally-provided source identifier of the content
nullable: true
source_url:
type: string
description: The URL that contains the source content
nullable: true
author:
type: string
description: The author of the content
nullable: true
image_url:
type: string
description: The feature image URL of the content
nullable: true
deprecated: true
metadata:
type: object
description: The arbitrary metadata associated with content
nullable: true
published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords players and
podcast feeds
nullable: true
video_published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords video players and
podcast video feeds
nullable: true
publish_date:
type: string
description: >-
Time at which the content was published or is scheduled to be
published (ISO 8601)
nullable: true
ads_enabled:
type: boolean
description: >-
Whether adverts will play for this content in the BeyondWords
players
nullable: true
auto_segment_updates_enabled:
type: boolean
description: >-
Whether the media files will be regenerated when the text content is
updated with `auto_segment`
nullable: true
title_voice_id:
type: integer
description: The id of the voice used to generate the audio of the title text.
nullable: true
summary_voice_id:
type: integer
description: The id of the voice used to generate the audio of the summary text.
nullable: true
body_voice_id:
type: integer
description: The id of the voice used to generate the audio of the body text.
nullable: true
type:
type: string
enum:
- auto_segment
- manual_segment
- audio_upload
nullable: true
description: >-
The content type. Possible values are `auto_segment`,
`manual_segment` or `audio_upload`
ai_summary_updates_enabled:
type: boolean
description: Whether the summary segments will be regenerated
language:
type: string
description: >-
The default language of the content, format is ISO 639-1 (with
underscore delimiter like en_GB)
nullable: true
background_track:
type: object
nullable: true
properties:
enabled:
type: boolean
track:
type: object
properties:
id:
type: integer
description: The track id
summarization_settings:
allOf:
- $ref: '#/components/schemas/requestBodySummarizationSettings'
nullable: true
feature_image:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
feature_video:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
requestBodyContentUpdateManualSegment:
title: Manual segment
description: Update content with manual segment type
type: object
properties:
title_enabled:
type: boolean
description: The flag to enable title segments in audio
body_enabled:
type: boolean
description: The flag to enable body segments in audio
summary_enabled:
type: boolean
description: The flag to enable summary audio
summary_title_enabled:
type: boolean
description: The flag to include title text and audio segments in summaries
source_id:
type: string
description: The externally-provided source identifier of the content
nullable: true
source_url:
type: string
description: The URL that contains the source content
nullable: true
author:
type: string
description: The author of the content
nullable: true
image_url:
type: string
description: The feature image URL of the content
nullable: true
deprecated: true
metadata:
type: object
description: The arbitrary metadata associated with content
nullable: true
published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords players and
podcast feeds
nullable: true
video_published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords video players and
podcast video feeds
nullable: true
publish_date:
type: string
description: >-
Time at which the content was published or is scheduled to be
published (ISO 8601)
nullable: true
segments:
type: array
description: The array of segments in the content
nullable: true
items:
type: object
properties:
id:
type: integer
description: Unique identifier for the object
nullable: true
section:
type: string
description: >-
The section type of the segment. Possible values are `title`,
`summary`, or `body`
enum:
- title
- summary
- body
nullable: true
marker:
type: string
description: >-
The marker associated with the segment to support the
'playback from segments' feature
nullable: true
text:
type: string
description: >-
The plain text for this segment. Required if content_type is
`text`
nullable: true
audio_url:
type: string
nullable: true
description: >-
The URL of the uploaded audio file for this segment. Required
if content_type is `audio`
image_url:
type: string
nullable: true
description: >-
The URL of the uploaded image file for this segment. Required
if content_type is `image`
video_url:
type: string
description: >-
URL to video file for visual content. Required when
content_type is `video`
nullable: true
start_time:
type: integer
description: >-
The start time of this segment within the audio and video
media files in milliseconds This may not exactly match the
summed durations because of audio alignment gaps
nullable: true
duration:
type: integer
description: The duration of this segment in milliseconds
nullable: true
voice:
type: object
nullable: true
properties:
id:
type: integer
description: Unique identifier for the voice
language:
type: object
nullable: true
properties:
code:
type: string
description: >-
The language of the segment, format is ISO 639-1 (with
underscore delimiter like en_GB)
xpath:
type: string
nullable: true
description: >-
XPath selector for locating this segment in the original HTML
document
md5:
type: string
nullable: true
description: MD5 hash of the segment text to support per-segment playback
video_settings:
type: object
nullable: true
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
pauses:
type: array
items:
type: object
properties:
time:
type: number
index:
type: number
ads_enabled:
type: boolean
description: >-
Whether adverts will play for this content in the BeyondWords
players
nullable: true
auto_segment_updates_enabled:
type: boolean
description: >-
Whether the media files will be regenerated when the text content is
updated with `auto_segment`
nullable: true
type:
type: string
enum:
- auto_segment
- manual_segment
- audio_upload
nullable: true
description: >-
The content type. Possible values are `auto_segment`,
`manual_segment` or `audio_upload`
ai_summary_updates_enabled:
type: boolean
description: Whether the summary segments will be regenerated
language:
type: string
description: >-
The default language of the content, format is ISO 639-1 (with
underscore delimiter like en_GB)
nullable: true
background_track:
type: object
nullable: true
properties:
enabled:
type: boolean
track:
type: object
properties:
id:
type: integer
description: The track id
summarization_settings:
allOf:
- $ref: '#/components/schemas/requestBodySummarizationSettings'
nullable: true
video_settings:
allOf:
- $ref: '#/components/schemas/requestBodyVideoSettings'
nullable: true
feature_image:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
feature_video:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
requestBodyContentUpdateAudioUpload:
title: Audio upload
description: Create content with audio upload type
type: object
properties:
title:
type: string
description: The content title
nullable: true
body:
type: string
description: The content body
nullable: true
source_id:
type: string
description: The externally-provided source identifier of the content
nullable: true
source_url:
type: string
description: The URL that contains the source content
nullable: true
author:
type: string
description: The author of the content
nullable: true
image_url:
type: string
description: The feature image URL of the content
nullable: true
deprecated: true
metadata:
type: object
description: The arbitrary metadata associated with content
nullable: true
published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords players and
podcast feeds
nullable: true
video_published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords video players and
podcast video feeds
nullable: true
publish_date:
type: string
description: >-
Time at which the content was published or is scheduled to be
published (ISO 8601)
nullable: true
segments:
type: array
description: The array of segments in the content
nullable: true
items:
type: object
properties:
id:
type: integer
description: Unique identifier for the object
nullable: true
section:
type: string
description: >-
The section type of the segment. Possible values are `title`,
`summary`, or `body`
enum:
- title
- summary
- body
nullable: true
marker:
type: string
description: >-
The marker associated with the segment to support the
'playback from segments' feature
nullable: true
text:
type: string
description: >-
The plain text for this segment. Required if content_type is
`text`
nullable: true
audio_url:
type: string
nullable: true
description: >-
The URL of the uploaded audio file for this segment. Required
if content_type is `audio`
image_url:
type: string
nullable: true
description: >-
The URL of the uploaded image file for this segment. Required
if content_type is `image`
video_url:
type: string
description: >-
URL to video file for visual content. Required when
content_type is `video`
nullable: true
start_time:
type: integer
description: >-
The start time of this segment within the audio and video
media files in milliseconds This may not exactly match the
summed durations because of audio alignment gaps
nullable: true
duration:
type: integer
description: The duration of this segment in milliseconds
nullable: true
video_settings:
type: object
nullable: true
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
pauses:
type: array
items:
type: object
properties:
time:
type: number
index:
type: number
ads_enabled:
type: boolean
description: >-
Whether adverts will play for this content in the BeyondWords
players
nullable: true
auto_segment_updates_enabled:
type: boolean
description: >-
Whether the media files will be regenerated when the text content is
updated with `auto_segment`
nullable: true
background_track:
type: object
nullable: true
properties:
enabled:
type: boolean
track:
type: object
properties:
id:
type: integer
description: The track id
summarization_settings:
allOf:
- $ref: '#/components/schemas/requestBodySummarizationSettings'
nullable: true
video_settings:
allOf:
- $ref: '#/components/schemas/requestBodyVideoSettings'
nullable: true
feature_image:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
feature_video:
type: object
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
type:
type: string
enum:
- auto_segment
- manual_segment
- audio_upload
nullable: true
description: >-
The content type. Possible values are `auto_segment`,
`manual_segment` or `audio_upload`
contentModel:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the content. Can be either a UUID or an
externally provided source_id
nullable: true
status:
type: string
enum:
- draft
- queued
- processing
- processed
- skipped
- error
description: >-
The current status of the content processing operation. This value
will change as the content is processed.
type:
type: string
enum:
- auto_segment
- manual_segment
- audio_upload
description: >-
The content type. Possible values are `auto_segment`,
`manual_segment` or `audio_upload`
title:
type: string
description: The content title
nullable: true
maxLength: 500
minLength: 1
summary:
type: string
description: The content summary
nullable: true
maxLength: 2000
body:
type: string
description: The content body
nullable: true
maxLength: 100000
title_enabled:
type: boolean
description: The flag to enable title segments in audio
body_enabled:
type: boolean
description: The flag to enable body segments in audio
summary_enabled:
type: boolean
description: The flag to enable summary audio
summary_title_enabled:
type: boolean
description: The flag to include title text and audio segments in summaries
source_id:
type: string
description: The externally-provided source identifier of the content
nullable: true
source_url:
type: string
description: The URL that contains the source content
nullable: true
author:
type: string
description: The author of the content
nullable: true
image_url:
type: string
description: The feature image URL of the content
nullable: true
deprecated: true
metadata:
type: object
description: The arbitrary metadata associated with content
nullable: true
audio:
type: array
description: The array of audio files for the entire content
items:
$ref: '#/components/schemas/contentAudioModel'
video:
type: array
description: The array of video files for the entire content
items:
$ref: '#/components/schemas/contentVideoModel'
audio_with_intro_outro:
type: array
items:
$ref: '#/components/schemas/contentAudioModel'
summarization:
type: object
properties:
audio:
type: array
description: The array of summary audio files for the entire content
items:
$ref: '#/components/schemas/contentAudioModel'
video:
type: array
description: The array of summary video files for the entire content
items:
$ref: '#/components/schemas/contentVideoModel'
segments:
type: array
description: The array of segments in the content
nullable: true
items:
type: object
properties:
id:
type: integer
description: Unique identifier for the segment
nullable: true
marker:
type: string
nullable: true
description: Custom marker for segment identification and playback control
maxLength: 255
xpath:
type: string
nullable: true
description: >-
XPath selector for locating this segment in the original HTML
document
maxLength: 1000
md5:
type: string
nullable: true
description: MD5 hash of the segment text to support per-segment playback
pattern: ^[a-f0-9]{32}$
section:
type: string
description: >-
Content section type: `title` for headlines, `summary` for
summaries, or `body` for main content
enum:
- title
- summary
- body
content_type:
type: string
description: >-
Segment content type: `text` for text-to-speech, `audio` for
pre-recorded audio, or `image` for visual content in videos
enum:
- text
- audio
- image
text:
type: string
description: >-
Plain text content for text-to-speech conversion. Required
when content_type is `text`
nullable: true
maxLength: 1000
audio_url:
type: string
nullable: true
description: >-
URL to pre-recorded audio file. Required when content_type is
`audio`
format: uri
maxLength: 2048
image_url:
type: string
nullable: true
description: >-
URL to image file for visual content. Required when
content_type is `image`
format: uri
maxLength: 2048
video_url:
type: string
nullable: true
description: >-
URL to video file for visual content. Required when
content_type is `video`
format: uri
maxLength: 2048
preprocessing_settings:
type: object
nullable: true
properties:
ai_preprocessing_enabled:
type: boolean
start_time:
type: integer
description: >-
Start time of this segment in the generated audio/video
(milliseconds). May differ from calculated duration due to
audio processing
nullable: true
minimum: 0
duration:
type: integer
description: Duration of this segment in milliseconds
nullable: true
minimum: 0
created:
type: string
format: date-time
description: Time at which the object was created (ISO 8601)
nullable: true
updated:
type: string
format: date-time
description: Time at which the object was updated (ISO 8601)
nullable: true
video_settings:
type: object
nullable: true
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
pauses:
type: array
items:
type: object
properties:
time:
type: number
index:
type: number
published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords players and
podcast feeds
video_published:
type: boolean
description: >-
Whether the content will appear in the BeyondWords video players and
podcast video feeds
publish_date:
type: string
description: >-
Time at which the content was published or is scheduled to be
published (ISO 8601)
nullable: true
ads_enabled:
type: boolean
description: >-
Whether adverts will play for this content in the BeyondWords
players
ai_summary_prompt:
type: string
nullable: true
description: The last used AI prompt for summary generation
maxLength: 1000
ai_summary_updates_enabled:
type: boolean
description: >-
Whether the summary segments will be regenerated when the text
content is updated
auto_segment_updates_enabled:
type: boolean
description: >-
Whether the media files will be regenerated when the text content is
updated with `auto_segment`
background_track:
type: object
nullable: true
properties:
enabled:
type: boolean
nullable: false
track:
type: object
nullable: true
properties:
id:
type: integer
name:
type: string
custom:
type: boolean
volume:
type: integer
url:
type: string
feature_image:
type: object
nullable: true
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
feature_video:
type: object
nullable: true
properties:
url:
type: string
video_settings:
type: object
properties:
enabled:
type: boolean
volume:
type: integer
crop_coordinates:
type: object
properties:
'16:9':
type: array
items:
type: number
maxItems: 4
'9:16':
type: array
items:
type: number
maxItems: 4
summarization_settings:
allOf:
- $ref: '#/components/schemas/summarizationSettingsModel'
nullable: true
video_settings:
type: object
nullable: true
properties:
enabled:
type: boolean
description: When true, video generation is enabled for this content
audio_and_waveform_enabled:
type: boolean
description: >-
When true, video includes audio and animated waveform
visualization
background_color:
type: string
maxLength: 100
content_image_enabled:
type: boolean
description: When true, uses the content's featured image as video background
image_extraction_enabled:
type: boolean
description: >-
When true, automatically extracts images from HTML content for
video backgrounds
logo_image_position:
type: string
enum:
- top-left
- top-right
logo_image_url:
type: string
format: uri
maxLength: 2048
pan_and_zoom_enabled:
type: boolean
description: When true, applies pan and zoom effects to background images
text_transform:
type: string
enum:
- none
- uppercase
- lowercase
- titlecase
description: Text transformation to apply to captions
text_background_color:
type: string
maxLength: 100
description: Background color for text captions (CSS color format)
text_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the text background
text_captions_enabled:
type: boolean
description: When true, displays text captions overlaid on the video
text_color:
type: string
maxLength: 100
description: Color of the text captions (CSS color format)
text_secondary_color:
type: string
maxLength: 100
description: >-
Color of the text captions to show on every other scene (CSS
color format)
text_highlight_color:
type: string
maxLength: 100
nullable: true
description: Color of highlighted text during playback (CSS color format)
text_highlight_secondary_color:
type: string
maxLength: 100
nullable: true
description: >-
Color of highlighted text to show on every other scene (CSS
color format)
text_highlight_background_color:
type: string
maxLength: 100
description: >-
Color of the background behind the highlighted text (CSS color
format, supports linear-gradient(to right, ...))
text_highlight_secondary_background_color:
type: string
maxLength: 100
nullable: true
description: >-
Color of the background behind the highlighted text to show on
every other scene (CSS color format, supports linear-gradient(to
right, ...))
text_highlight_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the highlight text background
text_shadow:
type: string
maxLength: 200
description: >-
Text shadow of non-highlighted words (CSS format, supports
linear-gradient(to right, ...))
text_highlight_shadow:
type: string
maxLength: 200
nullable: true
description: >-
Text shadow of highlighted words (CSS format, supports
linear-gradient(to right, ...))
text_stroke:
type: string
maxLength: 200
description: >-
Text outline of non-highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
text_highlight_stroke:
type: string
maxLength: 200
nullable: true
description: >-
Text outline of highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
text_fonts:
type: array
items:
type: string
maxLength: 255
maxItems: 10
description: >-
List of font families to use for text rendering (prioritized by
glyph coverage)
text_font_size:
type: integer
minimum: 30
maximum: 90
description: Font size for text captions (30-90)
text_width:
type: number
minimum: 0
maximum: 1
description: Maximum width of text as a ratio of the frame width.
text_lines:
type: integer
nullable: true
minimum: 1
maximum: 5
description: Maximum number of text lines to display simultaneously (1-5)
text_words:
type: integer
nullable: true
minimum: 1
description: Maximum number of words to show per line
text_horizontal_align:
type: string
enum:
- start
- center
- end
description: >-
The horizontal alignment of text lines, either 'start',
'center', or 'end'. A value of 'start' aligns the text to the
left for left-to-right languages, right otherwise. A value of
'end' aligns the text to the right for left-to-right languages,
left otherwise.
text_vertical_align:
type: string
enum:
- start
- center
- end
description: >-
The vertical alignment of text lines, either 'start' (top),
'center', or 'end' (bottom).
text_horizontal_offset:
type: number
description: >-
The horizontal offset of text relative to the frame width,
between -1.0 and 1.0
text_vertical_offset:
type: number
description: >-
The vertical offset of text relative to the frame height,
between -1.0 and 1.0
text_animation:
type: string
enum:
- classic
- reveal
- karaoke
- pop
description: The text animation to show
entrance_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The image entrance animation to show
exit_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The image exit animation to show
waveform_color:
type: string
maxLength: 100
description: Color of the audio waveform visualization (CSS color format)
playback_mode:
type: string
enum:
- cycle
- space-evenly
- follow-article
description: >-
How images are displayed: cycle (repeat), space-evenly
(distribute), or follow-article (match text position)
cycle_time:
type: integer
minimum: 1000
maximum: 60000
description: >-
Duration to show each image when playback_mode is 'cycle'
(milliseconds, 1-60 seconds)
variants:
type: array
items:
type: string
sizes:
type: array
items:
type: object
properties:
name:
type: string
description:
type: string
nullable: true
width:
type: integer
height:
type: integer
enabled:
type: boolean
template:
$ref: '#/components/schemas/videoSettingsTemplatesModel'
nullable: true
preprocessing_settings:
type: object
nullable: true
properties:
ai_preprocessing_enabled:
type: boolean
description: >-
When true, AI preprocessing is applied to improve text
normalization quality
language:
type: string
description: The default language of the content
nullable: true
created:
type: string
format: date-time
description: Time at which the object was created (ISO 8601)
updated:
type: string
format: date-time
description: Time at which the object was updated (ISO 8601)
requestBodySummarizationSettings:
type: object
properties:
enabled:
type: boolean
nullable: false
description: When true, AI-powered summarization is enabled
model:
type: string
enum:
- gpt-5-nano
- gpt-5-mini
- gpt-5
- gpt-5.1
prompt:
type: string
nullable: true
description: Custom prompt for AI summarization generation
temperature:
type: number
nullable: true
description: >-
Controls randomness in AI summarization (0.0 = deterministic, 2.0 =
very random)
minimum: 0
maximum: 2
limit_token_usage:
type: integer
nullable: true
description: Maximum number of tokens to use for AI summarization
minimum: 1
maximum: 3000
template:
type: object
nullable: true
properties:
id:
type: integer
slug:
type: string
description: The summarization settings template slug
requestBodyVideoSettings:
type: object
properties:
enabled:
type: boolean
description: When true, video generation is enabled for this content or project
logo_image_url:
type: string
nullable: true
description: >-
The logo that should appear in the corner of the video. Defaults to
the BeyondWords logo.
format: uri
maxLength: 2048
logo_image_position:
type: string
enum:
- top-left
- top-right
description: The position of the logo that appears in the corner of the video.
background_color:
type: string
description: >-
The background color of the video when there is no image. Supports
CSS colors including linear-gradient(to right, ...)
text_transform:
type: string
enum:
- none
- uppercase
- lowercase
- titlecase
description: Text transformation to apply to captions
text_background_color:
type: string
description: >-
The background color to show behind text. Supports CSS colors
including linear-gradient(to right, ...)
text_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the text background
text_color:
type: string
description: >-
The foreground color of text. Supports CSS colors including
linear-gradient(to right, ...)
text_secondary_color:
type: string
nullable: true
description: >-
Color of the text captions to show on every other scene. (CSS color
format)
text_highlight_color:
type: string
nullable: true
description: >-
The foreground color of text whilst the word is being read out.
Supports CSS colors including linear-gradient(to right, ...)
text_highlight_secondary_color:
type: string
nullable: true
description: >-
Color of highlighted text to show on every other scene. Supports CSS
colors including linear-gradient(to right, ...)
text_highlight_background_color:
type: string
maxLength: 100
description: >-
Color of the background behind the highlighted text (CSS color
format, supports linear-gradient(to right, ...))
text_highlight_secondary_background_color:
type: string
maxLength: 100
nullable: true
description: >-
Color of the background behind the highlighted text to show on every
other scene (CSS color format, supports linear-gradient(to right,
...))
text_highlight_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the highlight text background
text_shadow:
type: string
description: >-
Text shadow of non-highlighted words (CSS format, supports
linear-gradient(to right, ...))
text_highlight_shadow:
type: string
description: >-
Text shadow of highlighted words (CSS format, supports
linear-gradient(to right, ...))
nullable: true
text_stroke:
type: string
description: >-
Text outline of non-highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
text_highlight_stroke:
type: string
description: >-
Text outline of highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
nullable: true
text_fonts:
type: array
items:
type: string
description: >-
A list of fonts to use. Fonts will be prioritized automatically
based on glyph coverage for the text. The default fonts are
built-in, but you can include remote URLs to custom fonts in .ttf or
.otf format.
text_font_size:
type: integer
minimum: 30
maximum: 90
description: Font size for text captions (30-90).
text_width:
type: number
minimum: 0
maximum: 1
description: Maximum width of text as a ratio of the frame width.
text_lines:
type: integer
nullable: true
description: >-
The maximum number of lines of text to show at once. Must be between
1 and 5. If not specified, text_lines will default to landscape=4,
square=5, portrait=5.
minimum: 1
maximum: 5
text_words:
type: integer
nullable: true
minimum: 1
description: Maximum number of words to show per line
text_horizontal_align:
type: string
nullable: false
enum:
- start
- center
- end
description: >-
The horizontal alignment of text lines, either 'start', 'center', or
'end'. A value of 'start' aligns the text to the left for
left-to-right languages, right otherwise. A value of 'end' aligns
the text to the right for left-to-right languages, left otherwise.
text_vertical_align:
type: string
nullable: false
enum:
- start
- center
- end
description: >-
The vertical alignment of text lines, either 'start' (top),
'center', or 'end' (bottom).
text_horizontal_offset:
type: number
description: >-
The horizontal offset of text relative to the frame width, between
-1.0 and 1.0
text_vertical_offset:
type: number
description: >-
The vertical offset of text relative to the frame height, between
-1.0 and 1.0
text_animation:
type: string
enum:
- classic
- reveal
- karaoke
- pop
description: The text animation to show
entrance_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The entrance animation for image and video segments
exit_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The exit animation for image and video segments
waveform_color:
type: string
description: >-
The color of the audio waveform bars. Supports CSS colors including
linear-gradient(to right, ...)
content_image_enabled:
type: boolean
description: When true, uses the content's featured image as video background
image_extraction_enabled:
type: boolean
description: >-
When true, automatically extracts images from HTML content.
Alternatively, set the data-beyondwords-image='true' attribute.
pan_and_zoom_enabled:
type: boolean
description: When true, applies pan and zoom effects to background images
audio_and_waveform_enabled:
type: boolean
description: When true, video includes audio and animated waveform visualization
text_captions_enabled:
type: boolean
description: When true, displays text captions overlaid on the video
playback_mode:
type: string
enum:
- cycle
- space-evenly
- follow-article
description: >-
The playback mode for images in the video. There are three available
options. A value of 'cycle' will cycle through images, potentially
repeating them according to cycle_time. A value of 'space-evenly'
will space images evenly throughout the video without repeating
them. A value of 'follow-article' will show images at the point when
they appear in the article. Note that 'follow-article' is not
applicable for summaries which have different text.
cycle_time:
type: integer
description: >-
The time in milliseconds to show each image when playback_mode is
set to 'cycle'.
minimum: 1000
maximum: 60000
variants:
type: array
items:
type: string
sizes:
type: array
items:
type: object
properties:
name:
type: string
description:
type: string
nullable: true
width:
type: integer
height:
type: integer
enabled:
type: boolean
template:
type: object
nullable: true
properties:
id:
type: integer
slug:
type: string
description: The video settings template slug
contentAudioModel:
type: object
properties:
id:
type: integer
description: Unique identifier for the object
variant:
type: string
enum:
- article
- summary
description: The variant type of the audio content
video_size:
type: object
nullable: true
properties:
name:
type: string
description:
type: string
nullable: true
width:
type: integer
height:
type: integer
content_type:
type: string
enum:
- audio/mpeg
- application/x-mpegURL
description: MIME type of the audio file (MP3 or HLS playlist)
nullable: true
url:
type: string
description: Direct URL to the audio file
nullable: true
format: uri
duration:
type: integer
description: Duration of the audio file in milliseconds
nullable: true
base64_file:
type: string
description: Base64-encoded content of HLS playlist metadata files
nullable: true
contentVideoModel:
type: object
properties:
id:
type: integer
description: Unique identifier for the object
variant:
type: string
enum:
- article
- summary
description: The variant type of the video content
video_size:
type: object
nullable: true
properties:
name:
type: string
description:
type: string
nullable: true
width:
type: integer
height:
type: integer
content_type:
type: string
enum:
- video/mp4
- application/x-mpegURL
description: MIME type of the video file (MP4 or HLS playlist)
nullable: true
url:
type: string
description: Direct URL to the video file
nullable: true
duration:
type: integer
description: Duration of the video file in milliseconds
nullable: true
base64_file:
type: string
description: >-
The content of the media file encoded as base64. Only present for
.m3u8 metadata files
nullable: true
summarizationSettingsModel:
type: object
properties:
enabled:
type: boolean
nullable: false
description: When true, AI-powered summarization is enabled
prompt:
type: string
nullable: true
description: Custom prompt for AI summarization generation
model:
type: string
enum:
- gpt-5-nano
- gpt-5-mini
- gpt-5
- gpt-5.1
nullable: true
temperature:
type: number
nullable: true
description: >-
Controls randomness in AI summarization (0.0 = deterministic, 2.0 =
very random)
minimum: 0
maximum: 2
limit_token_usage:
type: integer
nullable: true
description: Maximum number of tokens to use for AI summarization
minimum: 1
maximum: 3000
template:
$ref: '#/components/schemas/summarizationSettingsTemplatesModel'
nullable: true
videoSettingsTemplatesModel:
type: array
items:
$ref: '#/components/schemas/videoSettingsTemplateModel'
summarizationSettingsTemplatesModel:
type: array
items:
$ref: '#/components/schemas/summarizationSettingsTemplateModel'
videoSettingsTemplateModel:
type: object
properties:
id:
type: integer
slug:
type: string
description: Unique identifier for the object
name:
type: string
nullable: false
logo_image_url:
type: string
nullable: true
description: >-
The logo that should appear in the corner of the video. Defaults to
the BeyondWords logo.
format: uri
maxLength: 2048
logo_image_position:
type: string
nullable: false
enum:
- top-left
- top-right
description: The position of the logo that appears in the corner of the video.
background_color:
type: string
nullable: false
description: >-
The background color of the video when there is no image. Supports
CSS colors including linear-gradient(to right, ...)
text_transform:
type: string
enum:
- none
- uppercase
- lowercase
- titlecase
description: Text transformation to apply to captions
text_background_color:
type: string
nullable: false
description: >-
The background color to show behind text. Supports CSS colors
including linear-gradient(to right, ...)
text_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the text background
text_color:
type: string
nullable: false
description: >-
The foreground color of text. Supports CSS colors including
linear-gradient(to right, ...)
text_secondary_color:
type: string
nullable: true
description: >-
Color of the text captions to show on every other scene (CSS color
format)
text_highlight_color:
type: string
nullable: true
description: >-
The foreground color of text whilst the word is being read out.
Supports CSS colors including linear-gradient(to right, ...)
text_highlight_secondary_color:
type: string
maxLength: 100
nullable: true
description: >-
Color of highlighted text to show on every other scene. Supports CSS
colors including linear-gradient(to right, ...)
text_highlight_background_color:
type: string
maxLength: 100
description: >-
Color of the background behind the highlighted text (CSS color
format, supports linear-gradient(to right, ...))
text_highlight_secondary_background_color:
type: string
maxLength: 100
nullable: true
description: >-
Color of the background behind the highlighted text to show on every
other scene (CSS color format, supports linear-gradient(to right,
...))
text_highlight_background_radius:
type: number
minimum: 0
maximum: 100
description: Border radius of the highlight text background
text_shadow:
type: string
maxLength: 200
description: >-
Text shadow of non-highlighted words (CSS format, supports
linear-gradient(to right, ...))
text_highlight_shadow:
type: string
maxLength: 200
nullable: true
description: >-
Text shadow of highlighted words (CSS format, supports
linear-gradient(to right, ...))
text_stroke:
type: string
maxLength: 200
description: >-
Text outline of non-highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
text_highlight_stroke:
type: string
maxLength: 200
nullable: true
description: >-
Text outline of highlighted words (CSS format, supports
linear-gradient(to right, ...) and inside/center/outside)
text_fonts:
type: array
nullable: false
items:
type: string
description: >-
A list of fonts to use. Fonts will be prioritized automatically
based on glyph coverage for the text. The default fonts are
built-in, but you can include remote URLs to custom fonts in .ttf or
.otf format.
text_font_size:
type: integer
minimum: 30
maximum: 90
description: Font size for text captions (30-90).
text_width:
type: number
minimum: 0
maximum: 1
description: Maximum width of text as a ratio of the frame width.
text_lines:
type: integer
nullable: true
description: >-
The maximum number of lines of text to show at once. Must be between
1 and 5. If not specified, text_lines will default to landscape=4,
square=5, portrait=5.
minimum: 1
maximum: 5
text_words:
type: integer
nullable: true
minimum: 1
description: Maximum number of words to show per line
text_horizontal_align:
type: string
nullable: false
enum:
- start
- center
- end
description: >-
The horizontal alignment of text lines, either 'start', 'center', or
'end'. A value of 'start' aligns the text to the left for
left-to-right languages, right otherwise. A value of 'end' aligns
the text to the right for left-to-right languages, left otherwise.
text_vertical_align:
type: string
nullable: false
enum:
- start
- center
- end
description: >-
The vertical alignment of text lines, either 'start' (top),
'center', or 'end' (bottom).
text_horizontal_offset:
type: number
description: >-
The horizontal offset of text relative to the frame width, between
-1.0 and 1.0
text_vertical_offset:
type: number
description: >-
The vertical offset of text relative to the frame height, between
-1.0 and 1.0
text_animation:
type: string
enum:
- classic
- reveal
- karaoke
- pop
description: The text animation to show
entrance_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The entrance animation for image and video segments
exit_animation:
type: string
enum:
- none
- fade
- zoom-in
- zoom-out
- slide-up
- slide-down
- slide-left
- slide-right
- pop
description: The exit animation for image and video segments
waveform_color:
type: string
nullable: false
description: >-
The color of the audio waveform bars. Supports CSS colors including
linear-gradient(to right, ...)
content_image_enabled:
type: boolean
nullable: false
description: When true, uses the content's featured image as video background
image_extraction_enabled:
type: boolean
nullable: false
description: >-
When true, automatically extracts images from HTML content.
Alternatively, set the data-beyondwords-image='true' attribute.
pan_and_zoom_enabled:
type: boolean
nullable: false
description: When true, applies pan and zoom effects to background images
audio_and_waveform_enabled:
type: boolean
nullable: false
description: When true, video includes audio and animated waveform visualization
text_captions_enabled:
type: boolean
nullable: false
description: When true, displays text captions overlaid on the video
playback_mode:
type: string
nullable: false
enum:
- cycle
- space-evenly
- follow-article
description: >-
The playback mode for images in the video. There are three available
options. A value of 'cycle' will cycle through images, potentially
repeating them according to cycle_time. A value of 'space-evenly'
will space images evenly throughout the video without repeating
them. A value of 'follow-article' will show images at the point when
they appear in the article. Note that 'follow-article' is not
applicable for summaries which have different text.
cycle_time:
type: integer
nullable: false
description: >-
The time in milliseconds to show each image when playback_mode is
set to 'cycle'.
minimum: 1000
maximum: 60000
preview_url:
type: string
nullable: true
template:
$ref: '#/components/schemas/videoSettingsTemplatesModel'
nullable: true
summarizationSettingsTemplateModel:
type: object
properties:
id:
type: integer
slug:
type: string
description: Unique identifier for the object
name:
type: string
nullable: false
model:
type: string
enum:
- gpt-5-nano
- gpt-5-mini
- gpt-5
- gpt-5.1
nullable: true
prompt:
type: string
nullable: true
description: Custom prompt for AI summarization generation
maxLength: 3000
temperature:
type: number
nullable: true
description: >-
Controls randomness in AI summarization (0.0 = deterministic, 2.0 =
very random)
minimum: 0
maximum: 2
limit_token_usage:
type: integer
nullable: true
description: Maximum number of tokens to use for AI summarization
minimum: 1
maximum: 500
examples:
requestBodyUpdateAutoSegmentContentRequestExample:
summary: Sample auto_segment content update request
value:
title: Example title
summary: >-
This article is about
TTS
body: Example body
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
title_voice_id: 1
summary_voice_id: 1
body_voice_id: 1
requestBodyUpdateManualSegmentContentRequestExample:
summary: Sample manual_segment content update request
value:
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
segments:
- id: 1
section: title
content_type: text
text: This is a title
voice:
id: 1
preprocessing_settings:
ai_preprocessing_enabled: true
- id: 2
section: body
content_type: text
text: This is new paragraph
voice:
id: 1
preprocessing_settings: null
- id: 3
section: body
content_type: image
image_url: https://example.com/image.jpeg
- id: 4
section: body
content_type: text
text: This is another paragraph
voice:
id: 1
- id: 5
section: body
content_type: audio
audio_url: https://example.com/image.mp3
- id: 6
section: body
content_type: text
text: This is another paragraph
voice:
id: 1
published: true
publish_date: 2023-01-01 00:00:00 UTC
ads_enabled: true
auto_segment_updates_enabled: true
requestBodyUpdateAudioUploadContentRequestExample:
summary: Sample audio_upload content update request
value:
title: Podcast episode title
body: Podcast episode description
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
segments:
- section: title
content_type: audio
audio_url: https://example.com/image.mp3
published: true
publish_date: 2023-01-01 00:00:00 UTC
ads_enabled: true
auto_segment_updates_enabled: false
contentExample:
summary: A sample content item request
value:
id: d7dfd636-098c-4b1b-83e5-15a3cba5a0bd
status: processed
type: auto_segment
title: Example title
summary: >-
This article is about
TTS
body: Example body
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
created: 2023-01-01 00:00:00 UTC
updated: 2023-01-01 00:00:05 UTC
securitySchemes:
apiKey:
type: apiKey
name: X-Api-Key
in: header
````