> For the complete documentation index, see [llms.txt](https://docs.3q.video/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.3q.video/rest-api/integration-example.md).

# Integration Example

**Uploading and Embedding Videos in a Third-Party Platform.** This guide demonstrates how to integrate the 3Q Platform into an external application, such as a Content Management System (CMS), Digital Asset Management (DAM) system, or a custom video platform.

In this example, a third-party application uploads a video to 3Q, stores the corresponding references in its own database, and uses the **Playout ID** to embed the Video Player or retrieve streaming URLs for a custom player.

### Integration Workflow

The integration consists of six steps:

1. **Authenticate** with the 3Q REST API.
2. **Upload a video** to an existing On-Demand project.
3. **Store the File ID** and associate it with the corresponding record in your database.
4. **Retrieve the Playout ID** for embedding the video.
5. **Embed the video** using the 3Q Player SDK or use streaming URLs for a custom player.
6. **Synchronize changes** using webhooks when media processing or video updates occur.

#### Integration Architecture

The third-party platform remains responsible for managing its own content records, while 3Q handles media processing, hosting, and streaming delivery.

For example, an article in your CMS can reference a video stored on 3Q without storing the original media file on your own infrastructure.

### Step 1: Authenticate with the REST API

The 3Q REST API uses Bearer Token authentication. See how this works in our [Guide](https://docs.3q.video/rest-api/guide.md).

API requests must include the authentication token in the `Authorization` header.

```
Authorization: Bearer YOUR_API_TOKEN
```

The API base URL is:

```
https://api.3qsdn.com/v3/
```

{% hint style="info" %}
For security reasons, API credentials should only be used on your backend and must never be exposed in client-side JavaScript.
{% endhint %}

### Step 2: Upload a Video

To upload a video, first select the On-Demand project in which the file should be stored.

{% hint style="info" %}
&#x20;A project is like a "folder" or content pool. You'll find more information [here](https://docs.3q.video/user-guide-new-ui/projects/on-demand.md).
{% endhint %}

Each project has a unique Project ID.

The file upload resource is:

```
POST /projects/{projectId}/files
```

The actual upload request must follow the file upload specification in the API reference.

For example, your application might upload a file called `product-demo.mp4` from its backend to the selected 3Q project.

After a successful upload, your application should retain the resulting 3Q File ID for further operations.

{% hint style="info" %}
**Important:** Uploading a video does not necessarily mean it is immediately available for playback. Depending on the project configuration and processing workflow, the file may still need to be encoded, packaged, or published. You can use [Webhooks](https://docs.3q.video/rest-api/webhooks.md) to automatically receive updates.
{% endhint %}

### Step 3: Store the Video Reference in Your Database

Instead of storing the actual video file in your application database, store its reference to the corresponding 3Q media asset.

A possible database structure could look like this:

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Field</td><td>Example</td><td>Description</td></tr><tr><td><code>id</code></td><td>42</td><td>Internal media record ID</td></tr><tr><td><code>article_id</code></td><td>125</td><td>ID of the associated CMS article</td></tr><tr><td><code>provider</code></td><td>3q</td><td>Video hosting provider</td></tr><tr><td><code>project_id</code></td><td>105489</td><td>3Q Project ID</td></tr><tr><td><code>file_id</code></td><td>12676565</td><td>3Q File ID</td></tr><tr><td><code>playout_id</code></td><td>UUID</td><td>3Q Playout ID</td></tr><tr><td><code>status</code></td><td>processing</td><td>Internal processing state</td></tr></tbody></table>

This allows your application to associate a video hosted on 3Q with any internal object, such as an article, product, course, or event.

The internal record remains independent of the video hosting infrastructure.

### Step 4: Retrieve the Playout ID

Each video can have one or more playout configurations.

A **Playout ID** identifies a playback configuration and is used to integrate the video into websites and applications. The 3Q platform automatically creates a default playout for media files. Additional playouts can be configured if different players or playback configurations are required.

Once the Playout ID is available, store it alongside the File ID in your database.

{% hint style="info" %}
**Recommended:** Use the Playout ID as the primary reference for frontend playback integrations and the File ID for backend asset management.
{% endhint %}

### Step 5: Embed the Video

There are two common ways to integrate the hosted video into your third-party platform.

#### Option A: Using the 3Q Player SDK (Recommended)

The 3Q Player SDK provides a complete playback solution, including adaptive streaming, subtitles, multiple audio tracks, analytics, and other configurable player features.

It is recommend to protect the embedded video or audio file against unauthorized playback. For this you can use different [protection methods](https://docs.3q.video/user-guide-new-ui/projects/content-protection.md).

The example below assumes that the 3Q Player SDK has already been loaded on the page.

```
<div id="player"></div>

<script>
  const player = new js3q({
    playoutId: "YOUR_PLAYOUT_ID",
    container: "player"
  });
</script>
```

Replace `YOUR_PLAYOUT_ID` with the Playout ID stored in your database.

In a typical CMS integration, your backend retrieves the Playout ID from the corresponding content record and provides it to your frontend.

The frontend can then initialize the 3Q Video Player dynamically.

This approach allows you to manage player configurations centrally without updating the embedding code for every individual video.

#### Option B: Using Streaming URLs with a Custom Player

If your application already uses a proprietary player or a third-party player library, you can retrieve the streaming URLs provided by 3Q.

Supported streaming formats include:

* **HLS (HTTP Live Streaming)**
* **MPEG-DASH**

These URLs can be used with compatible players such as hls.js, Shaka Player, or native playback components.

In this scenario, your backend retrieves the available streaming URLs for the selected asset and provides the appropriate URL to the frontend.

For example, an HLS-compatible player can use the HLS manifest URL for playback.

Keep in mind that direct streaming URLs are associated with the underlying media resources and may change when the asset is modified.

### Step 6: Synchronize Media Changes with Webhooks

For automated integrations, we recommend using **webhooks** to synchronize media changes between 3Q and your own platform.

Webhooks can notify your application when relevant events occur, allowing you to update the corresponding database records automatically.

Typical scenarios include:

* A new video has been processed.
* File metadata has changed.
* A file has been replaced or reprocessed.
* A file has been deleted.

When your backend receives a relevant event, it should identify the corresponding media record and retrieve any updated information required by the integration.

This is particularly important when your application uses direct streaming URLs instead of the 3Q Player SDK.

### Important: Playout IDs vs. Streaming URLs

The distinction between Playout IDs and direct streaming URLs is important when implementing a long-term integration.

| <p><br></p>                     | Playout ID                                             | Streaming URL                         |
| ------------------------------- | ------------------------------------------------------ | ------------------------------------- |
| Intended use                    | 3Q Player integration                                  | Custom or third-party players         |
| Stable reference                | Yes, for supported replacement and copy/move workflows | Not guaranteed                        |
| Media processing changes        | Usually no embed update required                       | URLs may need to be refreshed         |
| Player configuration            | Centrally managed through 3Q                           | Managed by the third-party player     |
| Recommended for CMS integration | Yes                                                    | Only when custom playback is required |

{% hint style="info" %}
**Recommendation:** When replacing a video with a new version or copying/moving it between projects through the supported 3Q workflows, the existing Playout ID is preserved. This allows your embedded player to continue working without changing the reference stored in your database.
{% endhint %}

Direct streaming URLs, such as HLS or MPEG-DASH manifests, can change after operations including replacement, trimming, repackaging, or copying.

If your integration relies on these URLs, use the 3Q Webhooks module to detect relevant changes and refresh the stored streaming information.

### Best Practices

For reliable integrations, we recommend the following:

* Store both the **File ID** and **Playout ID** to separate asset management from playback integration.
* Keep API credentials on your backend.
* Use the 3Q Player SDK whenever possible.
* Treat direct streaming URLs as potentially changeable resources.
* Use webhooks to synchronize processing, metadata, and deletion events.
* Check publication and processing status before making newly uploaded content available to end users.

### Further Documentation

* [REST API Guide](https://docs.3q.video/rest-api/guide)
* [REST API Reference](https://api.3qsdn.com/v3/doc)
* [Webhooks](https://docs.3q.video/rest-api/webhooks)
* [Player SDK Documentation](https://player.docs.3q.video/)
* [On-Demand Projects](https://docs.3q.video/user-guide-new-ui/projects/on-demand)
