Create and generate content

POST

projects

{project_id}

content

curl --request POST \
  --url https://api.beyondwords.io/v1/projects/{project_id}/content \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "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>",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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
}
'

{
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "status": "queued",
  "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>",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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"
  },
  "audio": [],
  "video": [],
  "segments": [],
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "created": "2023-01-01 00:00:00 UTC",
  "updated": "2023-01-01 00:00:05 UTC"
}

This is the primary endpoint for generating audio and video. Submit a new content item and BeyondWords queues processing based on the type you provide. See Processing types for request body examples. After creating, set up webhooks to be notified when processing completes via audio.updated. To update an existing item and re-run generation, use Update content or Regenerate content.

Authorizations

X-Api-Key

string

header

required

Path Parameters

project_id

string

required

The numeric ID of your project

Query Parameters

segments

enum<string>

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

Available options:

partial,

full

Body

application/json

Auto segment
Manual segment
Audio upload

Create content with auto segment type

type

enum<string>

default:auto_segment

required

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

Available options:

auto_segment

body

string

required

The content body

title

string

The content title

summary

string

The content summary

title_enabled

boolean

When true, generates audio for the title segment

body_enabled

boolean

When true, generates audio for the body text segments

summary_enabled

boolean

When true, generates audio for the summary content

summary_title_enabled

boolean

When true, includes title text and audio in generated summaries

source_id

string | null

The externally-provided source identifier of the content

source_url

string<uri> | null

The URL that contains the source content

Maximum string length: 2048

author

string | null

The author of the content

image_url

string<uri> | null

deprecated

The feature image URL of the content

Maximum string length: 2048

metadata

object

The arbitrary metadata associated with content

published

boolean | null

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

video_published

boolean | null

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

publish_date

string<date-time> | null

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

ads_enabled

boolean | null

Whether adverts will play for this content in the BeyondWords players

auto_segment_updates_enabled

boolean | null

Whether the media files will be regenerated when the text content is updated with auto_segment

title_voice_id

integer | null

The id of the voice used to generate the audio of the title text.

Required range: x >= 1

summary_voice_id

integer | null

The id of the voice used to generate the audio of the summary text.

Required range: x >= 1

body_voice_id

integer | null

The id of the voice used to generate the audio of the body text.

Required range: x >= 1

ai_summary_updates_enabled

boolean

Whether the summary segments will be regenerated

language

string | null

The default language of the content, format is ISO 639-1 (with underscore delimiter like en_GB)

Maximum string length: 10

Pattern: ^[a-z]{2}(_[A-Z]{2})?$

background_track

object

Show child attributes

summarization_settings

object

Show child attributes

video_settings

object

Show child attributes

feature_image

object

Show child attributes

feature_video

object

Show child attributes

Response

201 - 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.

Available options:

draft,

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

image_url

string | null

deprecated

The feature image URL of the content

metadata

object

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

background_track

object

Show child attributes

feature_image

object

Show child attributes

feature_video

object

Show child attributes

summarization_settings

object

Show child attributes

video_settings

object

Show child attributes

preprocessing_settings

object

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)

Get contentReturns a single content item from your project. Use the `segments` query parameter to include segment-level data.

curl --request POST \
  --url https://api.beyondwords.io/v1/projects/{project_id}/content \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "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>",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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
}
'

{
  "id": "d7dfd636-098c-4b1b-83e5-15a3cba5a0bd",
  "status": "queued",
  "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>",
  "title_enabled": true,
  "body_enabled": true,
  "summary_enabled": true,
  "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"
  },
  "audio": [],
  "video": [],
  "segments": [],
  "ads_enabled": true,
  "auto_segment_updates_enabled": true,
  "created": "2023-01-01 00:00:00 UTC",
  "updated": "2023-01-01 00:00:05 UTC"
}