Skip to content
SpeakDocs

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

Deeper nested fields are not listed. See the example response below for the full shape.

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._id string
data.meta object
data.mediaId string
data.folderIds any[]
data.mediaType string
data.token string
data.privacyMode string
data.page string
data.iframe string

Deeper nested fields are not listed. See the example response below for the full shape.

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

Deeper nested fields are not listed. See the example response below for the full shape.

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._id string
data.meta object
data.mediaId string
data.folderIds any[]
data.embedType string
data.isActive boolean
data.isDeleted boolean
data.analytics any[]
data.companyId string
data.userId string
data.mediaType string
data.token string
data.createdAt string (date-time)
data.updatedAt string (date-time)
data.__v integer
data.password string

Deeper nested fields are not listed. See the example response below for the full shape.

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
All sections

Type to search…

↑↓ navigate↵ selectEsc close