Skip to content
Speak AIDocs

Embed Speak AI media and transcripts in your pages

Create and update Speak AI media embeds, check whether a piece of media is already embedded, and get the iframe URL to drop into your own page.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

The Speak AI API exposes 5 media embeds endpoints under the base URL https://api.speakai.co/v1. Every request needs the x-speakai-key and x-access-token headers described in Authentication.

Embed Individual Media Player or the Folder (as repository) to make the insights, transcription and insights publicly visible or share with others.

What can you do with the media embeds endpoints?

Speak AI groups these 5 endpoints under the media embeds resource. Each entry below links to the full reference for that endpoint further down this page.

Check Embed

GET/embed

Checks if an embed already exits and returns status and token id.

Parameters

Parameter In Type Required Description
mediaId query string No ID of the media file to check for an embed
Example request
curl -X GET 'https://api.speakai.co/v1/embed' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data.meta object
data._id string
data.mediaId string
data.token string
data.privacyMode string
data.meta – 9 more fields
Field Type
backgroundImg string
logo string
primaryColor string
isDataVizDownloadable boolean
isSEOIndexing boolean
isTitle boolean
isDescription boolean
callToActionButtons any[]
features object[]
features[].name string
features[].isActive boolean

Example response, application/json. Arrays are shortened to one entry and long strings are cut.

{
  "status": "success",
  "data": {
    "meta": {
      "backgroundImg": "",
      "logo": "",
      "primaryColor": "",
      "isDataVizDownloadable": true,
      "isSEOIndexing": true,
      "isTitle": true,
      "isDescription": true,
      "callToActionButtons": [],
      "features": [
        {
          "name": "transcript",
          "isActive": true
        }
      ]
    },
    "_id": "61280763ec13780791f004b2",
    "mediaId": "e4e3079e3da9",
    "token": "daily-standup-august-23-2021-239819a49b2d",
    "privacyMode": "public"
  }
}

Create Embed

POST/embed

Create an Interactive Media Player by passing the value for mediaId OR folderIds

  • By passing mediaId - Create an individual media player.

  • By passing folderIds - Create a repository for a folder to share with others.

Make sure you have access to Shareable Media Repository in your subscription.

Request rules. Send either a media id or a set of folder ids. A non-empty media id creates a single media player, and the request is rejected with 403 unless your plan includes the media player feature and your role allows sharing media. An empty or absent media id switches to the library path, which is rejected with 403 unless your plan includes the media library feature. A media id that matches no media file in your workspace returns 404.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
mediaId string The id of the media file you want to publish as a standalone player. Send it to create a media player. Leave it out, or send an empty string, when you want a shared library built from folders instead. If that media file already has a player, you get the existing one back instead of a duplicate. Optional. An empty string is allowed and is treated the same as leaving it out.
folderIds string[] The folders whose media you want to publish together as a shared library. Send folder ids with no media id to create one. If a library already exists for the same folder ids in the same order, you get that one back instead of a duplicate. Whenever you send folder ids, they are recorded on the new embed and a password is generated for it, and that password comes back in the response. Optional. A list of folder ids, with no minimum or maximum length. Folder ids that match nothing in your workspace do not cause an error.
Example request
curl -X POST 'https://api.speakai.co/v1/embed' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data – 9 more fields
Field Type
_id string
meta object
mediaId string
folderIds any[]
mediaType string
token string
privacyMode string
page string
iframe string
meta – 10 more fields
Field Type
callToActionButtons object[]
callToActionButtons[].url string
callToActionButtons[].label string
features object[]
features[].name string
features[].isActive boolean
isDataVizDownloadable boolean
isDescription boolean
isSEOIndexing boolean
isRemarks boolean
isPromptAsk boolean
isPromptHistory boolean
isTitle boolean
primaryColor string

Example response (Create Embed), application/json. Arrays are shortened to one entry and long strings are cut.

{
  "status": "success",
  "data": {
    "_id": "65660bf97f916888ccc2f4ca",
    "meta": {
      "callToActionButtons": [
        {
          "url": "https://speakai.co",
          "label": "Speak Ai"
        }
      ],
      "features": [
        {
          "name": "labels",
          "isActive": true
        }
      ],
      "isDataVizDownloadable": false,
      "isDescription": false,
      "isSEOIndexing": false,
      "isRemarks": true,
      "isPromptAsk": true,
      "isPromptHistory": true,
      "isTitle": true,
      "primaryColor": "#c42860"
    },
    "mediaId": "3afc714552cd",
    "folderIds": [],
    "mediaType": "video",
    "token": "how-to-edit-the-transcript-79a590aa126b",
    "privacyMode": "private",
    "page": "",
    "iframe": ""
  }
}

Update Embed

PUT/embed/{embedId}

Update an existing Embed Media Player.

  • Make sure to pass in path embedId to update your existing player

Request rules. The embedId value in the path is required and must be a string. Nothing in the body is required on its own, but only meta, privacyMode, password and mediaId change anything. Password handling runs only when privacyMode is present: private stores the trimmed password you send, or an empty one if you send none, and any other privacy value clears the password. The media file’s own privacy mode is changed only when mediaId is present and not empty, and a media id that matches no media file in your workspace returns 404. Inside meta.callToActionButtons every item must carry both url and label. Inside meta.features every item must carry both name and isActive. An embed id that matches no embed returns 404.

Parameters

Parameter In Type Required Description
embedId path string Yes

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field Type Description
meta object The look and behavior of the embedded player. Every top level key you send is applied on its own, so keys you leave out keep their current values. Arrays and the lead capture group are the exception: sending one replaces the stored value in full. Optional. Unknown keys inside it are rejected with 400.
privacyMode string Controls whether viewers need a password. Send private together with the password you want, or send public to remove password protection. Leave this out and the current password is left alone, so an update that only changes appearance cannot wipe it. When you also send a media id, the media file itself is switched to the same privacy mode. Optional. An empty string is allowed. The value is not checked against the list, and anything other than private is treated as public and clears the password. One of: public, private .
password string The password viewers must enter. It is used only when you also send a privacy mode of private, and surrounding spaces are trimmed. Send private with no password, or with an empty string, and the embed ends up with no password at all. Optional. An empty string is allowed. Ignored unless privacyMode is present.
mediaId string The media file behind this embed. Send it when you are changing the privacy mode, so the media file is switched over too. It does not move the embed to a different media file. Optional. An empty string is allowed and is treated as not sent. A non-empty value that does not match a media file in your workspace returns 404.
folderIds string[] Accepted but ignored. This endpoint does not change which folders a library embed covers, so sending different folder ids has no effect. Optional. A list of folder ids.
mediaType string Accepted but ignored. The media type is set when the embed is created and this endpoint does not change it. Optional. An empty string is allowed. The value is not checked against the list. One of: audio, video, text, media, csv .
embedType string Accepted but ignored. Whether the embed is a single media player, a folder library or a dashboard is decided when it is created and cannot be switched here. Optional. An empty string is allowed. The value is not checked against the list. One of: mediaPlayer, repository, dashboard .
size string Accepted but ignored. The stored iframe size is not changed by this endpoint. Optional. An empty string is allowed.
isActive boolean Accepted but ignored. This endpoint does not turn an embed on or off. Optional.
_id string The embed’s own id. The Speak app sends it when it posts a whole embed object back. The embed that gets updated is always the one named in the path, so you can leave this out.
meta – 23 more fields
Field Type Description
backgroundImg string The background image shown behind the player. Send an empty string to clear it. If you send a signed delivery URL it is converted back to its underlying storage location before being saved, and a delivery URL that cannot be converted leaves the current image unchanged. Optional. An empty string is allowed and clears the image. Null is accepted but ignored, so it leaves the current image unchanged.
logo string The logo shown on the player. Send an empty string to remove it. As with the background image, a signed delivery URL is converted back to its storage location before being saved, and one that cannot be converted leaves the current logo unchanged. Optional. An empty string is allowed and clears the logo. Null is accepted but ignored, so it leaves the current logo unchanged.
callToActionButtons object[] The buttons shown to viewers alongside the media. Send the full list you want, because this replaces any buttons already set. Send an empty array to remove them all. Optional. Each item must have both url and label, and both must be strings.
callToActionButtons[].url string Where the button sends the viewer. Required on every button you send.
callToActionButtons[].label string The text shown on the button. Required on every button you send.
features object[] Which insight categories are switched on in the player, such as keywords, topics or sentiment. Send the full list you want, because this replaces the stored list. The list an embed starts with is built from the insights found on its media. Optional. Each item must have name and isActive. Only the name and the active state of each entry are stored. The list also carries rows that are not insights: on a shared dashboard, { "name": "fieldsFocus", "isActive": false } stops recordings opened from the dashboard leading with their fields, and with no fieldsFocus row they do. Keep such rows when you resend the list.
features[].name string The insight category this entry controls. Use the same name the insight is reported under, for example keywords, topics or sentiment. Custom categories you have created use their own names. Required on every feature you send.
features[].isActive boolean Set it to true to show this category to viewers and false to hide it. Required on every feature you send.
features[].isCustom boolean Accepted on a feature entry but not saved. Only the name and the active state of each feature are stored, so sending this has no effect. Optional.
isTitle boolean Set it to true to show the media title in the player and false to hide it. Optional. A new embed inherits this from your workspace player settings, which start it on.
isDescription boolean Set it to true to show the media description in the player and false to hide it. Optional. A new embed inherits this from your workspace player settings, which start it on.
isRemarks boolean Set it to true to let viewers see remarks and comments left on the media. Optional. A new embed inherits this from your workspace player settings, which start it off.
isSEOIndexing boolean Set it to true to let search engines index the shared page and false to keep it out of search results. Optional. A new embed inherits this from your workspace player settings, which start it on.
isDataVizDownloadable boolean Set it to true to let viewers download the charts and visualizations shown in the player. Optional. A new embed inherits this from your workspace player settings, which start it on.
isMediaExport boolean Set it to true to let viewers export or download the media itself. Optional. A new embed inherits this from your workspace player settings, which start it off.
isPromptAsk boolean Set it to true to let viewers ask the AI assistant questions about the media from inside the player. Optional. A new embed inherits this from your workspace player settings, which start it off.
isPromptHistory boolean Set it to true to show viewers the earlier questions and answers from the assistant, and false to start every visitor with a clean slate. Optional. A new embed inherits this from your workspace player settings, which start it off.
chatWelcomeMessage string The greeting the AI assistant opens with in the player. Send an empty string to use no greeting. Optional. An empty string is allowed, and null is accepted and stored as no greeting.
assistantTemplateId string The saved assistant template the player’s AI chat answers with, so viewers get the tone and instructions you have already set up. Send an empty string to fall back to the default assistant. Optional. An empty string is allowed, and null is accepted and stored as no template.
primaryColor string The accent color used for controls and highlights in the player. Send a CSS color value such as a hex code. Optional. An empty string is allowed. A new embed inherits this from your workspace player settings, which start it at a dark grey. The value is stored as sent and is not checked for a valid color.
titleColor string The color of the title text in the player. Send a CSS color value such as a hex code. Optional. An empty string is allowed. A new embed inherits this from your workspace player settings, which start it at a dark grey. The value is stored as sent and is not checked for a valid color.
logoDark string A shared dashboard’s logo for viewers in dark mode. It must be an image already stored in Speak AI as a logo; any other link returns 400. When empty, the dashboard uses logo. Optional. An empty string or null clears it.
theme string Forces a shared dashboard into light or dark for every viewer and hides their theme switch. An empty string lets each viewer choose. Optional. Null clears it. One of: light, dark, `` .
backgroundColor string A hex color (#rgb or #rrggbb) for a shared dashboard’s page background. Pair it with theme so text stays readable. Optional. An empty string or null clears it.
fontFamily string A Google Fonts family name for a shared dashboard, such as Arimo: letters, digits and spaces, up to 60 characters. Anything else returns 400. It overrides your account font for this embed. Optional. An empty string or null falls back to the account font.
leadCapture object Asks viewers for their email before they can watch, so you can see who is viewing. Send the full set of lead capture values you want, because sending this replaces the whole group rather than merging into it. It stays inactive until you switch it on. Optional. Unknown keys inside it are rejected with 400.
leadCapture.isEnabled boolean The main switch. Set it to true to prompt viewers for their details, and while it is false no prompt appears no matter what the other lead capture values say. Optional. New embeds start with this off.
leadCapture.collectName boolean Set it to true to ask viewers for their name as well as their email. Optional. New embeds start with this off.
leadCapture.requireConsent boolean Set it to true to make viewers tick a consent box before they can submit their details. Optional. New embeds start with this off.
leadCapture.consentText string The wording shown next to the consent box. Write your own so it matches your privacy policy. Optional. An empty string is allowed, and null is accepted.
isLabels boolean Set it to true to show the media’s labels read-only in a media or folder embed. Viewers can never add or change labels. Optional. Off by default.
isComments boolean Set it to true to show the media’s comment threads read-only in a media or folder embed. Viewers can never comment. Optional. Off by default.
Example request
curl -X PUT 'https://api.speakai.co/v1/embed/65660bf97f916888ccc2f4ca' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data – 16 more fields
Field Type
_id string
meta object
mediaId string
folderIds any[]
embedType string
isActive boolean
isDeleted boolean
analytics any[]
companyId string
userId string
mediaType string
token string
createdAt string (date-time)
updatedAt string (date-time)
__v integer
password string
meta – 12 more fields
Field Type
backgroundImg string
callToActionButtons object[]
callToActionButtons[].url string
callToActionButtons[].label string
features object[]
features[].name string
features[].isActive boolean
isDataVizDownloadable boolean
isDescription boolean
isSEOIndexing boolean
isRemarks boolean
isPromptAsk boolean
isPromptHistory boolean
isTitle boolean
logo string
primaryColor string

Example response (Update Embed), application/json. Arrays are shortened to one entry and long strings are cut.

{
  "status": "success",
  "data": {
    "_id": "65660bf97f916888ccc2f4ca",
    "meta": {
      "backgroundImg": "",
      "callToActionButtons": [
        {
          "url": "https://speakai.co",
          "label": "Speak Ai"
        }
      ],
      "features": [
        {
          "name": "keywords",
          "isActive": true
        }
      ],
      "isDataVizDownloadable": true,
      "isDescription": true,
      "isSEOIndexing": true,
      "isRemarks": true,
      "isPromptAsk": false,
      "isPromptHistory": true,
      "isTitle": true,
      "logo": "",
      "primaryColor": "#c42860"
    },
    "mediaId": "3afc714552cd",
    "folderIds": [],
    "embedType": "mediaPlayer",
    "isActive": true,
    "isDeleted": false,
    "analytics": [],
    "companyId": "5e21c8dd2d77242c64214816",
    "userId": "5d03a9d5d4bca272e9c8cf89",
    "mediaType": "video",
    "token": "how-to-edit-the-transcript-79a590aa126b",
    "createdAt": "2023-11-28T15:49:13.511Z",
    "updatedAt": "2023-11-28T15:55:58.403Z",
    "__v": 0,
    "password": ""
  }
}

Get Iframe URL

GET/embed/iframe

Get Embed Iframe and Page URL

Either pass mediaId for individaul file.

OR

Pass folderId for a repository URLs.

Parameters

Parameter In Type Required Description
mediaId query string No Either Folder ID or Media ID
folderId query string No Either Folder ID or Media ID
Example request
curl -X GET 'https://api.speakai.co/v1/embed/iframe?mediaId='\'''\''' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data.iframe string
data.page string

Example response (Get Iframe URL), application/json. Arrays are shortened to one entry and long strings are cut.

{
  "status": "success",
  "data": {
    "iframe": "<iframe style=\"height: 800px !important; width: 960px !important;\" src=\"https://embed.speakai.co/iframe/how-to-find-your-first-analyzed-video-edq6fuxmemn\" frameborder=\"0\" scrolling...",
    "page": "https://embed.speakai.co/how-to-find-your-first-analyzed-video-edq6fuxmemn"
  }
}

Check Embed Privacy Mode

GET/embed/privacyState

Endpoint Description

This endpoint retrieves the privacy state of the application based on the provided token. It is primarily used to check whether the current privacy settings are secure.

Request

  • Method: GET

  • URL: https://api.speakai.co/v1/embed/privacyState?token={token}

Query Parameters
  • token (string): A unique token that identifies the user’s session or request. This parameter is required for the request to be processed.

Response

The response will contain the following structure:

  • status (string): A status message indicating the result of the request.

  • data (object): An object containing the privacy state information.

  • isSecure (boolean): A boolean value indicating whether the privacy settings are secure (true or false).

Example Response

{
 "status": "",
 "data": {
 "isSecure": true
 }
}

This response indicates that the privacy settings are currently secure.

Parameters

Parameter In Type Required Description
token query string No
Example request
curl -X GET 'https://api.speakai.co/v1/embed/privacyState' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 OK

Response body, application/json.

Field Type
status string
data object
data.isSecure boolean

Example response (Check Embed Privacy Mode), application/json.

{
  "status": "success",
  "data": {
    "isSecure": false
  }
}

Get an API key on the Speak AI developer page.

Navigation

Get Speak AI

Web PlatformSign in or start free in your browser
Log inStart free
iOS appiPhone and iPadAndroid appPhones and tabletsMCP ServerConnect Claude, ChatGPT and other AI tools
All sections

Type to search…

↑↓ navigate↵ selectEsc close