---
title: "Embed Speak AI media and transcripts in your pages"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Speak AI media and transcripts in your pages


import EndpointIndex from "@/components/api/EndpointIndex.astro";

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](/api/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.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/embed`](#get-embed) | Check Embed |
| `POST` | [`/embed`](#post-embed) | Create Embed |
| `PUT` | [`/embed/{embedId}`](#put-embed-embed-id) | Update Embed |
| `GET` | [`/embed/iframe`](#get-embed-iframe) | Get Iframe URL |
| `GET` | [`/embed/privacyState`](#get-embed-privacy-state) | Check Embed Privacy Mode |

<h2 id="get-embed">Check Embed</h2>

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 |

<div slot="code">

<CodePanel label="Example request">

```bash
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'
```

</CodePanel>

<ResponsePanel id="get-embed" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`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.

```json
{
  "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"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-embed">Create Embed</h2>

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 body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `folderIds` | string[] |

<div slot="code">

<CodePanel label="Example request">

```bash
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 '{
  "folderIds": [
"e88575b384b6"
  ]
}'
```

</CodePanel>

<ResponsePanel id="post-embed" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`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.

```json
{
  "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": ""
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="put-embed-embed-id">Update Embed</h2>

Update an existing Embed Media Player.

- Make sure to pass in path `embedId` to update your existing player

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `embedId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `_id` | string |
| `mediaId` | string |
| `meta` | object |
| `meta.backgroundImg` | string |
| `meta.callToActionButtons` | object[] |
| `meta.features` | object[] |
| `meta.isDataVizDownloadable` | boolean |
| `meta.isDescription` | boolean |
| `meta.isSEOIndexing` | boolean |
| `meta.isRemarks` | boolean |
| `meta.isPromptAsk` | boolean |
| `meta.isPromptHistory` | boolean |
| `meta.isTitle` | boolean |
| `meta.logo` | string |
| `meta.primaryColor` | string |

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

<div slot="code">

<CodePanel label="Example request">

```bash
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 '{
  "_id": "65660bf97f916888ccc2f4ca",
  "mediaId": "3afc714552cd",
  "meta": {
"backgroundImg": "",
"callToActionButtons": [
  {
    "url": "https://speakai.co",
    "label": "Speak Ai"
  }
],
"features": [
  {
    "name": "keywords",
    "isActive": true
  },
  {
    "name": "transcript",
    "isActive": true
  }
],
"isDataVizDownloadable": true,
"isDescription": true,
"isSEOIndexing": true,
"isRemarks": true,
"isPromptAsk": false,
"isPromptHistory": true,
"isTitle": true,
"logo": "",
"primaryColor": "#c42860"
  }
}'
```

</CodePanel>

<ResponsePanel id="put-embed-embed-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`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.

```json
{
  "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": ""
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-embed-iframe">Get Iframe URL</h2>

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 |

<div slot="code">

<CodePanel label="Example request">

```bash
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'
```

</CodePanel>

<ResponsePanel id="get-embed-iframe" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`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.

```json
{
  "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"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-embed-privacy-state">Check Embed Privacy Mode</h2>

#### 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

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

```

This response indicates that the privacy settings are currently secure.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | query | string | No |  |

<div slot="code">

<CodePanel label="Example request">

```bash
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'
```

</CodePanel>

<ResponsePanel id="get-embed-privacy-state" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.isSecure` | boolean |

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

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

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-embeds).

Source: https://docs.speakai.co/api/embeds/index.mdx