FastPix Ruby SDK

The FastPix Ruby SDK is a type-safe Ruby client for the FastPix video API. From any Ruby application you can upload and manage on-demand video, create and manage live streams and simulcasts, create and secure playback IDs, manage playlists and signing keys, retrieve video analytics, and use in-video AI features.

Find more in the SDK reference

For all methods, runnable examples, and advanced usage, see the FastPix Ruby SDK on GitHub.

Before you begin

Make sure you have:

• Ruby 3.2 or later
• Bundler
• Internet access
• A FastPix account
• A FastPix Access Token and Secret Key, generated from the FastPix Dashboard. See Activate your account.

FastPix uses HTTP Basic Authentication. The SDK maps your credentials as follows:

Security: Never commit your Access Token or Secret Key to source control. Use environment variables or a secure credential-management system.

Follow the steps below in order, and do not skip the verification steps. If installation, dependency loading, authentication, client initialization, or the first API request fails, fix that problem before continuing.

Check your Ruby version

ruby -v

The output is similar to ruby 3.2.2 .... The SDK supports Ruby 3.2 and later. If your version is earlier than 3.2, install a supported version before continuing.

You can also run the check programmatically:

ruby -e 'v = RUBY_VERSION.split(".").map(&:to_i); abort("Ruby 3.2+ is required. Found #{RUBY_VERSION}") if v < [3,2,0]; puts "Ruby #{RUBY_VERSION} OK"'

Note: macOS may include an older system Ruby. Installing a newer Ruby with Homebrew (brew install ruby) does not automatically make it the default ruby command. Add the Homebrew Ruby to your PATH and confirm with which ruby.

Check your Bundler installation

The SDK uses Bundler to install and manage dependencies.

bundle -v

The expected output is similar to Bundler version 2.x.x. If Bundler is not installed, install it before continuing:

gem install bundler

Create a Ruby project

Create a directory for your application and initialize a Bundler project:

mkdir fastpix-ruby-demo
cd fastpix-ruby-demo
bundle init

bundle init creates a Gemfile in the project directory. You add the SDK to it in the next step.

Install the FastPix SDK

The FastPix Ruby SDK is distributed as the fastpixapi gem. Add it to your project with Bundler:

bundle add fastpixapi

If you are not using Bundler, install the gem directly:

gem install fastpixapi

Verify the SDK installation

Confirm that the gem is installed:

gem list '^fastpixapi$'

The output lists fastpixapi and the installed version. Then confirm that Ruby can load the SDK:

bundle exec ruby -e 'require "fastpixapi"; puts "FastPix Ruby SDK loaded successfully"'

The expected output is FastPix Ruby SDK loaded successfully. This confirms that Ruby can run the application, Bundler resolved the dependency, and the SDK can be loaded. If you installed with gem install instead of Bundler, drop bundle exec and run the command with ruby directly.

Configure authentication

FastPix uses HTTP Basic Authentication, where username is your Access Token and password is your Secret Key. For local development, set these as environment variables so they stay out of your source code:

# macOS and Linux
export FASTPIX_USERNAME="<YOUR_ACCESS_TOKEN>"
export FASTPIX_PASSWORD="<YOUR_SECRET_KEY>"

# Windows PowerShell
$env:FASTPIX_USERNAME="<YOUR_ACCESS_TOKEN>"
$env:FASTPIX_PASSWORD="<YOUR_SECRET_KEY>"

Verify that your credentials are set

Check that both variables are set without printing their values:

# macOS and Linux
[ -n "$FASTPIX_USERNAME" ] && echo "Access Token: set" || echo "Access Token: missing"
[ -n "$FASTPIX_PASSWORD" ] && echo "Secret Key: set" || echo "Secret Key: missing"

You can also validate both variables with Ruby:

ruby -e 'abort("FASTPIX_USERNAME is not set") if ENV["FASTPIX_USERNAME"].to_s.empty?; abort("FASTPIX_PASSWORD is not set") if ENV["FASTPIX_PASSWORD"].to_s.empty?; puts "FastPix credentials are configured"'

Both should report as set. If either is missing, set the corresponding environment variable before continuing.

Initialize the FastPix client

Create a file named main.rb:

require "json"
require "fastpixapi"
Models = ::FastpixClient::Models
abort("FASTPIX_USERNAME is not set") if ENV["FASTPIX_USERNAME"].to_s.empty?
abort("FASTPIX_PASSWORD is not set") if ENV["FASTPIX_PASSWORD"].to_s.empty?
client = ::FastpixClient::Fastpixapi.new(
  security: Models::Components::Security.new(
    username: ENV.fetch("FASTPIX_USERNAME"),
    password: ENV.fetch("FASTPIX_PASSWORD")
  )
)
puts "FastPix client initialized"

Run it:

bundle exec ruby main.rb

The expected output is FastPix client initialized. Initializing the client does not make an API request; a request happens only when you call an SDK operation such as client.input_video.create_media(...).

Make your first API request

The easiest way to verify the integration is to create media from a publicly accessible video URL. FastPix provides a sample video at https://static.fastpix.com/fp-sample-video.mp4.

Replace the contents of main.rb with:

require "json"
require "fastpixapi"
Models = ::FastpixClient::Models
abort("FASTPIX_USERNAME is not set") if ENV["FASTPIX_USERNAME"].to_s.empty?
abort("FASTPIX_PASSWORD is not set") if ENV["FASTPIX_PASSWORD"].to_s.empty?
client = ::FastpixClient::Fastpixapi.new(
  security: Models::Components::Security.new(
    username: ENV.fetch("FASTPIX_USERNAME"),
    password: ENV.fetch("FASTPIX_PASSWORD")
  )
)
request = Models::Components::CreateMediaRequest.new(
  inputs: [
    Models::Components::PullVideoInput.new(
      type: "video",
      url: "https://static.fastpix.com/fp-sample-video.mp4"
    )
  ],
  metadata: {
    "source" => "fastpix-ruby-demo"
  }
)
begin
  response = client.input_video.create_media(request: request)
  puts JSON.pretty_generate(JSON.parse(response.raw_response.body))
rescue FastpixClient::Models::Errors::APIError => e
  warn "FastPix API request failed"
  warn "Status: #{e.status_code}"
  warn "Message: #{e.message}"
  warn "Body: #{e.body}"
  exit 1
end

Run it:

bundle exec ruby main.rb

A successful request returns information about the newly created media asset, similar to:

{
  "success": true,
  "data": {
    "id": "..."
  }
}

The exact fields depend on the API response and the installed SDK version.

Capture the media ID

The create-media response contains the unique ID assigned to the media asset, at data.id:

{
  "success": true,
  "data": {
    "id": "12345678-1234-1234-1234-123456789abc"
  }
}

Save this value for later operations:

MEDIA_ID=<value returned in data.id>

A media_id is not the same as a playback_id. They identify different resources and are used for different operations.

Verify the integration

A successful create-media request confirms that Ruby is installed and supported, Bundler resolved the dependency, the SDK is installed and loadable, your credentials are configured, the client can authenticate, and FastPix returns a media ID.

Creating media is usually the first step in a FastPix on-demand workflow: you create the media, poll it until processing finishes, then create a playback ID to play it. The initial SDK integration is now complete.

Resources, error handling, and reference

The SDK is generated from the FastPix API specification, so the complete and always-current reference lives in the repo and the API docs:

• All resources, operations, error handling, and server selection: the FastPix Ruby SDK on GitHub, with runnable code in the examples directory.
• Media (upload, manage, playback, playlists, signing keys, DRM): Video on Demand API.
• Live (streams, simulcasts, live playback): Live Stream API.
• Video Data (metrics, views, dimensions, errors): Video Data API.
• In-video AI (summaries, chapters, named entities, moderation): In-Video AI.

What’s next

Want to go further? Browse runnable, end-to-end samples for the FastPix Ruby SDK in the examples folder of the GitHub repository.

Release notes

For a complete history of releases, improvements, and fixes, see the FastPix Ruby SDK CHANGELOG on GitHub.