Ruby SDK

This guide is your starting point for building robust video workflows using the FastPix Ruby SDK. Whether you're integrating livestreaming into a creator platform, building video-on-demand libraries, or powering short-form content apps, this SDK gives you fine-grained control over uploading, playback, and live distribution using simple Ruby syntax.

Before you start

Before installing and using the SDK, ensure your environment is properly configured. Here's what you’ll need:

Step 1: Installation

You can install the SDK in four different ways depending on your development environment:

Option 1: Install from GitHub (Recommended for most users)

If you're starting fresh, this is the easiest way to get started with the latest version.

gem install specific_install 
gem specific_install https://github.com/FastPix/fastpix-ruby.git 

Option 2: Add to your Gemfile (Bundler projects)

Ideal for projects already using Bundler.

gem 'fastpixapi', git: 'https://github.com/FastPix/fastpix-ruby.git' 

Then install dependencies:

bundle install

Option 3: Local development

Use this if you're contributing to the SDK or want to test local changes.

gem build fastpixapi.gemspec 
gem install ./fastpixapi-0.0.1.gem 

Option 4: From RubyGems (coming soon)

Once our SDK is published on RubyGems, you can simply run:

gem install fastpixapi 

Step 2: Import the SDK

Import the SDK to access media, livestream, and playback features in your Ruby app.

require 'fastpixapi'

PLEASE NOTE

If you’re using Bundler, the gem will be automatically available when you add it to your Gemfile.

Step 3: Initialization

FastPix uses HTTP Basic Authentication. Before making any API calls, you’ll need to obtain your credentials from the FastPix dashboard. The SDK uses different server URLs for different operations.

For Media operations

Use this client to manage uploads, media files, and playback.

require 'fastpixapi' 
 
# Initialize the SDK for Media Operations 
sdk = ::FastpixApiSDK::SDK.new( 
  server_url: 'https://api.fastpix.io/v1/on-demand', 
  security: Models::Components::Security.new( 
    username: 'your-access-token-id', 
    password: 'your-secret-key' 
  ) 
) 

For Live Stream operations

Use this instance for working with livestream creation and simulcast management.

require 'fastpixapi' 
 
# Initialize the SDK for Live Stream Operations 
sdk = ::FastpixApiSDK::SDK.new( 
  server_url: 'https://api.fastpix.io/v1/live-stream', 
  security: Models::Components::Security.new( 
    username: 'your-access-token-id', 
    password: 'your-secret-key' 
  ) 
) 

Environment variables

For security, always use environment variables to keep secrets out of your codebase.

sdk = ::FastpixApiSDK::SDK.new( 
  server_url: 'https://v1.fastpix.io', 
  security: Models::Components::Security.new( 
    username: ENV['FASTPIX_ACCESS_TOKEN_ID'], 
    password: ENV['FASTPIX_SECRET_KEY'] 
  ) 
) 

Perform Media Operations

The FastPix Ruby SDK provides comprehensive media management capabilities. Here are the key operations you can perform:

1.1 Create Media from URL

This endpoint allows developers or users to create a new video or audio media in FastPix using a publicly accessible URL. FastPix will fetch the media from the provided URL, process it, and store it on the platform for use.

For more details, refer to: Create Media From URL API documentation.

# Create media from a URL 
request = Models::Operations::CreateMediaRequestBody.new( 
  input: Models::Components::Input.new( 
    url: "https://example.com/video.mp4" 
  ), 
  metadata: Models::Components::CreateMediaRequestMetadata.new( 
    title: "My Video", 
    description: "A great video" 
  ), 
  max_resolution: Models::Components::CreateMediaRequestMaxResolution.new( 
    width: 1920, 
    height: 1080 
  ) 
) 
 
response = sdk.input_video.create_media(request) 
 
if response.media 
  media_id = response.media.id 
  puts "Media created! ID: #{media_id}" 
end

1.2 Upload Media from Device

This endpoint enables you to upload a video file directly from your local device to FastPix for processing and storage. When you invoke this API with your preferred media settings, the response returns an uploadId and a pre-signed URL, providing a streamlined experience for uploading.

For more details refer to Upload Media From Device API documentation.

# Upload media directly from your device 
upload_request = Models::Operations::DirectUploadVideoMediaRequestBody.new( 
  metadata: Models::Components::DirectUploadMetadata.new( 
    title: "Uploaded Video", 
    description: "Directly uploaded content" 
  ) 
) 
 
upload_response = sdk.input_video.direct_upload_video_media(upload_request) 
 
if upload_response.direct_upload 
  upload_url = upload_response.direct_upload.upload_url 
  puts "Upload URL: #{upload_url}" 
  # Use this URL to upload your video file 
end 

1.3 List All Media

This endpoint returns a list of all media files created from a URL or uploaded as file objects within your organization. Each media entry contains metadata such as the media ID, creation date, status, and type.

For more details refer to List All Media API documentation.

# List all media 
media_list = sdk.manage_videos.list_media 
 
# With pagination and sorting 
media_list = sdk.manage_videos.list_media( 
  limit: 20, 
  offset: 1, 
  order_by: Models::Operations::ListMediaOrderBy::DESC 
) 

1.4 Get Specific Media by ID

By calling this endpoint, you can retrieve detailed information about a specific media item, including its current status and a playbackId. This is particularly useful for retrieving specific media details when managing large content libraries.

For more details refer to Get Media by ID API documentation.

# Get specific media 
media = sdk.manage_videos.get_media( 
  Models::Operations::GetMediaRequest.new( 
    id: 'your-media-id' 
  ) 
) 

1.5 Update Media

This endpoint allows you to update specific parameters of an existing media file. You can modify the key-value pairs of the metadata that were provided during the creation of media from a URL or when uploading the media as a file object.

For more details refer to Update Media API documentation.

# Update media 
update_request = Models::Operations::UpdatedMediaRequestBody.new( 
  metadata: Models::Components::UpdatedMediaMetadata.new( 
    title: 'Updated Title', 
    description: 'Updated description' 
  ) 
) 
 
updated_media = sdk.manage_videos.updated_media( 
  Models::Operations::UpdatedMediaRequest.new( 
    id: 'your-media-id', 
    body: update_request 
  ) 
) 

1.6 Delete Media

This endpoint allows you to permanently delete a specific video or audio media file along with all associated data. This action is irreversible, and the media cannot be retrieved or played back once deleted.

For more details refer to Delete Media API documentation.

# Delete media 
sdk.manage_videos.delete_media( 
  Models::Operations::DeleteMediaRequest.new( 
    id: 'your-media-id' 
  ) 
) 

1.7 Create Media Playback ID

You can create a new playback ID for a specific media asset. This endpoint allows you to generate a new playback ID with a specified access policy, even if the media already has an existing playback ID.

For more details refer to Create Media Playback ID API documentation.

# Create playback ID for media 
media_playback_request = Models::Operations::CreateMediaPlaybackIdRequestBody.new( 
  access_policy: Models::Operations::CreateMediaPlaybackIdAccessPolicy::PUBLIC 
) 
 
media_playback_response = sdk.playback.create_media_playback_id( 
  Models::Operations::CreateMediaPlaybackIdRequest.new( 
    id: 'your-media-id', 
    body: media_playback_request 
  ) 
) 

1.8 Delete Media Playback ID

This endpoint allows you to remove a specific playback ID associated with a media asset. Deleting a playbackId will revoke access to the media content linked to that ID.

For more details refer to Delete Media Playback ID API documentation.

# Delete playback ID 
sdk.playback.delete_media_playback_id( 
  Models::Operations::DeleteMediaPlaybackIdRequest.new( 
    id: 'your-media-id', 
    playback_id: 'your-playback-id' 
  ) 
) 

Live Stream Operations

The FastPix Ruby SDK provides powerful live streaming capabilities. Here are the key operations you can perform:

2.1 Create a Live Stream

Allows you to initiate a new RTMP or SRT live stream on FastPix. Upon creating a stream, FastPix generates a unique stream key and SRT secret, which can be used with any broadcasting software (like OBS) to connect to FastPix’s RTMP or SRT servers.

For more details refer to Create Live Stream API documentation.

# Create a new live stream 
request = Models::Components::CreateLiveStreamRequest.new( 
  playback_settings: Models::Components::PlaybackSettings.new( 
    # Configure playback settings 
  ), 
  input_media_settings: Models::Components::InputMediaSettings.new( 
    metadata: Models::Components::CreateLiveStreamRequestMetadata.new( 
      title: 'My Live Stream', 
      description: 'An exciting live event' 
    ) 
  ) 
) 
 
response = sdk.start_live_stream.create_new_stream(request) 
 
if response.live_stream_response_dto 
  stream_id = response.live_stream_response_dto.stream_id 
  puts "Stream created successfully! ID: #{stream_id}" 
end 

2.2 List All Live Streams

Retrieves a list of all live streams associated with the user’s account (workspace). It provides an overview of both current and past live streams, including details like streamId, title, status, and creation time.

For more details refer to List All Live Streams API documentation.

# Get all live streams 
streams = sdk.manage_live_stream.get_all_streams 
 
# With pagination and sorting 
streams = sdk.manage_live_stream.get_all_streams( 
  limit: '20', 
  offset: '1', 
  order_by: Models::Operations::GetAllStreamsOrderBy::DESC 
) 

2.3 Get Live Stream by ID

This endpoint retrieves detailed information about a specific live stream by its unique streamId. It includes data such as the stream’s status (idle, preparing, active, disabled), metadata (title, description), and more.

For more details refer to Get Live Stream by ID API documentation.

# Get a specific stream 
stream = sdk.manage_live_stream.get_live_stream_by_id( 
  Models::Operations::GetLiveStreamByIdRequest.new( 
    id: 'your-stream-id' 
  ) 
) 

2.4 Update Live Stream

This endpoint allows users to modify the parameters of an existing live stream, such as its metadata (title, description) or the reconnect window. It’s useful for making changes to a stream that has already been created but not yet ended.

For more details refer to Update Live Stream API documentation.

# Update a stream 
update_request = Models::Operations::UpdateLiveStreamRequest.new( 
  id: 'your-stream-id', 
  body: Models::Operations::UpdateLiveStreamRequestBody.new( 
    metadata: Models::Components::PatchLiveStreamRequestMetadata.new( 
      title: 'Updated Stream Title' 
    ), 
    reconnect_window: 100 
  ) 
) 
 
updated_stream = sdk.manage_live_stream.update_live_stream(update_request) 

2.5 Delete Live Stream

Permanently removes a specified live stream from the workspace. If the stream is still active, the encoder will be disconnected, and the ingestion will stop. This action cannot be undone.

For more details refer to Delete Live Stream API documentation.

# Delete a stream 
delete_request = Models::Operations::DeleteLiveStreamRequest.new( 
  id: 'your-stream-id' 
) 
 
sdk.manage_live_stream.delete_live_stream(delete_request) 

2.6 Create Playback ID for Stream

Generates a new playback ID for the live stream, allowing viewers to access the stream through this ID. The playback ID can be shared with viewers for direct access to the live broadcast.

For more details refer to Create Live Stream Playback ID API documentation.

# Create playback ID for a stream 
playback_request = Models::Operations::CreatePlaybackIdOfStreamRequestBody.new( 
  access_policy: Models::Components::PlaybackIdRequestAccessPolicy::PUBLIC 
) 
 
playback_response = sdk.playback.create_playback_id_of_stream( 
  Models::Operations::CreatePlaybackIdOfStreamRequest.new( 
    id: 'your-stream-id', 
    body: playback_request 
  ) 
) 

2.7 Get Stream’s Playback ID

Retrieves details about a previously created playback ID. If you provide the distinct playback ID that was given back to you in the previous stream or playbackId create request, FastPix will provide the relevant playback details such as the access policy.

For more details refer to Get Live Stream Playback ID API documentation.

# Get stream's playback ID 
playback_id = sdk.playback.get_live_stream_playback_id( 
  Models::Operations::GetLiveStreamPlaybackIdRequest.new( 
    id: 'your-stream-id', 
    playback_id: 'your-playback-id' 
  ) 
) 

2.8 Delete Playback ID

Deletes a previously created playback ID for a live stream. This will prevent any new viewers from accessing the stream through the playback ID, though current viewers will be able to continue watching for a limited time before being disconnected.

For more details refer to Delete Live Stream Playback ID API documentation.

# Delete playback ID 
sdk.playback.delete_playback_id_of_stream( 
  Models::Operations::DeletePlaybackIdOfStreamRequest.new( 
    id: 'your-stream-id', 
    playback_id: 'your-playback-id' 
  ) 
) 

2.9 Create Simulcast

Lets you to create a simulcast for a parent live stream. A simulcast enables you to broadcast the live stream to multiple platforms simultaneously (e.g., YouTube, Facebook, or Twitch). This feature is useful for expanding your audience reach across different platforms. However, a simulcast can only be created when the parent live stream is in an idle state (i.e., not currently live or disabled). Additionally, only one simulcast target can be created per API call.

For more details refer to Create Simulcast  API documentation.

# Create a simulcast for a stream 
simulcast_request = Models::Operations::CreateSimulcastOfStreamRequestBody.new( 
  url: 'rtmp://hyd01.contribute.live-video.net/app/', 
  stream_key: 'live_1012464221_DuM8W004MoZYNxQEZ0czODgfHCFBhk', 
  metadata: Models::Components::SimulcastRequestMetadata.new( 
    livestream_name: 'Tech-Connect Summit' 
  ) 
) 
 
simulcast_response = sdk.simulcast_stream.create_simulcast_of_stream( 
  Models::Operations::CreateSimulcastOfStreamRequest.new( 
    id: 'your-stream-id', 
    body: simulcast_request 
  ) 
) 

2.10 Get Simulcast Details

Retrieves the details of a specific simulcast associated with a parent live stream. By providing both the streamId of the parent stream and the simulcastId, FastPix returns detailed information about the simulcast.

For more details refer to Get Simulcast Details API documentation.

# Get specific simulcast 
simulcast = sdk.simulcast_stream.get_specific_simulcast_of_stream( 
  Models::Operations::GetSpecificSimulcastOfStreamRequest.new( 
    id: 'your-stream-id', 
    simulcast_id: 'your-simulcast-id' 
  ) 
) 

2.11 Update Simulcast

Allows you to enable or disable a specific simulcast associated with a parent live stream. The status of the simulcast can be updated at any point, whether the live stream is active or idle.

For more details refer to Update Simulcast API documentation.

# Update simulcast 
update_simulcast_request = Models::Operations::UpdateSpecificSimulcastOfStreamRequest.new( 
  id: 'your-stream-id', 
  simulcast_id: 'your-simulcast-id', 
  body: Models::Operations::UpdateSpecificSimulcastOfStreamRequestBody.new( 
    is_enabled: false, 
    metadata: Models::Components::SimulcastUpdateRequestMetadata.new( 
      simulcast_name: 'Tech today' 
    ) 
  ) 
) 
 
updated_simulcast = sdk.simulcast_stream.update_specific_simulcast_of_stream(update_simulcast_request) 

2.12 Delete Simulcast

Allows you to delete a simulcast using its unique simulcastId, which was returned during the simulcast creation process. Deleting a simulcast stops the broadcast to the associated platform, but the parent stream will continue to run if it is live.

For more details refer to Delete Simulcast API documentation.

# Delete simulcast 
sdk.simulcast_stream.delete_simulcast_of_stream( 
  Models::Operations::DeleteSimulcastOfStreamRequest.new( 
    id: 'your-stream-id', 
    simulcast_id: 'your-simulcast-id' 
  ) 
) 

Error Handling

The FastPix Ruby SDK throws specific exception classes depending on what went wrong — whether it’s authentication, permissions, validation issues, or general API failures. You can handle each one with rescue, and build robust error-handling logic in your app.

By default, all API failures will raise a Models::Errors::APIError. This object gives you detailed insight into the failure:

Example: Handling common exceptions.

The SDK provides specific error classes for different scenarios:

begin 
  response = sdk.start_live_stream.create_new_stream(request) 

 
rescue Models::Errors::UnauthorizedError => e 
  puts "Authentication failed: #{e.message}" 
  # Handle authentication issues 

 
rescue Models::Errors::InvalidPermissionError => e 
  puts "Permission denied: #{e.message}" 
  # Handle permission issues 

 
rescue Models::Errors::ValidationErrorResponse => e 
  puts "Validation error: #{e.message}" 
  # Handle invalid request data 

 
rescue Models::Errors::NotFoundError => e 
  puts "Resource not found: #{e.message}" 
  # Handle missing resources 

 
rescue Models::Errors::BadRequestError => e 
  puts "Bad request: #{e.message}" 
  # Handle malformed requests 

 
rescue Errors::APIError => e 
  puts "API error: #{e.message}" 
  # Handle general API errors 

 
rescue => e 
  puts "Unexpected error: #{e.message}" 
  # Handle any other errors 
end

These errors follow a consistent structure and allow you to build application-level handling or logging around them.

Support & resources

• Documentation: Visit the FastPix API Reference for detailed API documentation
• GitHub Issues: Report bugs or request features on the GitHub repository
• FastPix Platform: 
• Contact us: Technical support