SAPI PHP SDK

1.0 | Introduction

The SAPI PHP SDK is an official Blue Billywig package that provides a PHP interface for the Server API (SAPI). It covers entity CRUD operations (mediaclips, playlists, channels, playouts, subtitles), file uploads to S3, and thumbnail URL generation. Both synchronous and asynchronous usage are supported via Guzzle.

GitHub repository: bluebillywig/bb-sapi-php-sdk

2.0 | Requirements

• PHP 8.1 or higher
• Composer

3.0 | Installation

composer require bluebillywig/bb-sapi-php-sdk

4.0 | Authentication

The SDK uses HOTP-based RPC token authentication. You need the token ID and shared secret from your Blue Billywig publication (see API key management).

The shared secret shown in your account settings has the format {id}-{hex_secret}, for example 490-55c491d354cfefb9b4d26cf22fbdd0a1. The number before the dash is the token ID; the hex string after the dash is the secret.

use BlueBillywig\Sdk;

$sdk = Sdk::withRPCTokenAuthentication(
    'my-publication', // publication name (subdomain of bbvms.com)
    490,              // token ID (the number before the dash)
    '55c491d354...'   // shared secret (the hex string after the dash)
);

The token is time-based with a 120-second validity window. Ensure your server clock is synchronized with NTP.

5.0 | Quick start

5.1 | List mediaclips

$response = $sdk->mediaclip->list(15, 0, 'createddate desc');
$data = $response->getDecodedBody();
print_r($data);

5.2 | Get a single mediaclip

$response = $sdk->mediaclip->get(12345);

if ($response->isOk()) {
    $clip = $response->getDecodedBody();
    echo $clip['title'];
}

5.3 | Create, update, and delete

// Create
$response = $sdk->mediaclip->create(['title' => 'My Video', 'status' => 'draft']);

// Update
$response = $sdk->mediaclip->update(12345, ['title' => 'Updated Title']);

// Delete (soft)
$sdk->mediaclip->delete(12345);

// Delete permanently
$sdk->mediaclip->delete(12345, true); // purge = true

The same pattern applies to $sdk->playlist, $sdk->channel, $sdk->playout, and $sdk->subtitle.

5.4 | Upload a video file

// 1. Initialize the upload
$initResponse = $sdk->mediaclip->initializeUpload('/path/to/video.mp4');
$initResponse->assertIsOk();
$uploadData = $initResponse->getDecodedBody();

// 2. Execute the upload
$sdk->mediaclip->helper->executeUpload('/path/to/video.mp4', $uploadData);

6.0 | Supported entities

Thumbnail URL generation is available as a helper method:

$url = $sdk->thumbnail->helper->getAbsoluteImagePath('/path/to/image.jpg', 640, 360);
// => https://my-publication.bbvms.com/image/640/360/path/to/image.jpg

7.0 | Full documentation

The GitHub README contains the complete method reference, asynchronous usage examples, response handling, and error handling details: github.com/bluebillywig/bb-sapi-php-sdk