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,
  "generate_audio": 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,
  "generate_audio": 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

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. 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 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,
  "generate_audio": 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,
  "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

Create and generate content

Authorizations

Path Parameters

Query Parameters

Body

Response