Skip to content
BranchesTags

Repository files navigation

FastPix Ruby SDK

Gem version Gem downloads license Ruby 3.2+

A robust, type-safe Ruby SDK for integrating Ruby applications with the FastPix video API.

The FastPix Ruby SDK lets you upload and manage on-demand video, create and manage live streams, create playback IDs, manage playlists and signing keys, retrieve video analytics, and use in-video AI capabilities.

Works with: Ruby 3.2+ · Bundler · RubyGems · FastPix API

📖 Docs: https://fastpix.com/docs/language-sdks/ruby-sdk 🚀 Free account: https://dashboard.fastpix.com

Jump to

Skip straight to a section without scrolling:

Get started API reference Help & more
Start here Available resources & operations FAQ
Before you begin Media workflow Which SDK?
Install the SDK Error handling Development
Create your first media Server selection Maturity
Verify your integration Examples Detailed usage

Start here

If you are using the FastPix Ruby SDK for the first time, follow these steps in order:

  1. Check your Ruby version
  2. Install the SDK
  3. Configure authentication
  4. Initialize the FastPix client
  5. Create your first media
  6. Verify your integration
  7. Understand the media workflow
  8. Explore the available APIs

Do not skip the verification steps. If a Ruby, dependency, or authentication problem occurs, fix it before continuing to the next API operation.

Before you begin

To use the FastPix Ruby SDK, make sure you have:

  • Ruby 3.2 or later.
  • Bundler.
  • Internet access.
  • A FastPix account.
  • A FastPix Access Token.
  • A FastPix Secret Key.

Environment and version support

Requirement Version Description
Ruby 3.2+ Core runtime environment
Bundler Latest Dependency management
Internet Required API communication and authentication
FastPix account Required Required for API credentials

The SDK is intended for Ruby 3.2 and later.

Authentication

FastPix uses HTTP Basic Authentication.

SDK value FastPix credential
username Access Token
password Secret Key

Follow the Authentication with Basic Auth guide to obtain your credentials.

For local development, set your credentials as environment variables:

export FASTPIX_USERNAME="your-access-token"
export FASTPIX_PASSWORD="your-secret-key"

Never commit credentials to source control. Use environment variables or a secure credential-management system.

Check your Ruby version

Before installing the SDK, verify that your Ruby version meets the minimum requirement:

ruby -v

You can also run this 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"'

If the command prints:

Ruby 3.2+ is required...

install a supported Ruby version before continuing.

macOS with Homebrew

If you use Homebrew on Apple Silicon:

brew install ruby

Add the Homebrew Ruby installation to your PATH:

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify that your shell is using the Homebrew Ruby:

which ruby
ruby -v

The which ruby command should return a path under:

/opt/homebrew/opt/ruby/bin/ruby

Note: macOS may include an older system Ruby. Installing a newer Ruby does not automatically make it the default ruby command.

Check Bundler

Verify that Bundler is available:

bundle -v

If Bundler is not installed:

gem install bundler

Verify the installation:

bundle -v

Install the SDK

The FastPix Ruby SDK is distributed as the fastpixapi RubyGem.

Install with Bundler

For an existing Ruby project, add the SDK to your project:

bundle add fastpixapi

Then verify that Ruby can load the SDK:

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

Install with RubyGems

If you are not using Bundler:

gem install fastpixapi

Verify the installation:

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

You can also check the installed gem:

gem list '^fastpixapi$'

Configure authentication

FastPix uses Basic Authentication. Set your Access Token and Secret Key as environment variables so they stay out of your source code:

export FASTPIX_USERNAME="your-access-token"
export FASTPIX_PASSWORD="your-secret-key"

Confirm that both variables are set without displaying their values:

[ -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"'

Security: Never print, commit, or hard-code your Access Token or Secret Key.

Initialize the FastPix client

Create a project directory, then initialize the client and create your first media:

mkdir fastpix-ruby-demo
cd fastpix-ruby-demo

Create your first media

The easiest way to verify your integration is to create media from a publicly accessible video URL.

FastPix provides a sample video:

https://static.fastpix.com/fp-sample-video.mp4

Create an example.rb file:

cat > example.rb <<'RUBY'
require "json"
require "fastpixapi"

Models = ::FastpixClient::Models

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-readme"
  }
)

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
RUBY

Run the example:

bundle exec ruby example.rb

If you installed the SDK with gem install, run:

ruby example.rb

More examples: For additional runnable examples, see the examples/ directory in this repository.

Verify your integration

A successful request returns a response containing the newly created media resource.

A successful response contains:

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

The data.id value is the unique media ID assigned to the media.

For an automated verification, use this version of the example:

cat > verify.rb <<'RUBY'
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-readme"
  }
)

begin
  response = client.input_video.create_media(request: request)
  body = JSON.parse(response.raw_response.body)

  abort("FastPix API returned success=false") unless body["success"]

  media_id = body.dig("data", "id")
  abort("FastPix API response did not contain data.id") unless media_id

  puts "Media created successfully"
  puts "Media ID: #{media_id}"
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
RUBY

Run it:

bundle exec ruby verify.rb

Expected output:

Media created successfully
Media ID: <media-id>

If you see this output, your Ruby environment, SDK installation, credentials, and connection to the FastPix API are working.

Understand the media workflow

Creating media is usually the first step in a FastPix on-demand video workflow. You create the media, poll it until processing finishes, then create a playback ID to play it.

FastPix media workflow: create media returns a media ID, you retrieve and poll the media until it is ready, then create a playback ID and play the video.

The media ID identifies the media resource in subsequent API calls.

A playback ID provides access to the media for playback.

For more information about the video-on-demand workflow, see the FastPix Video on Demand documentation.

Available Resources and Operations

Comprehensive Ruby SDK for FastPix platform integration with full API coverage.

Media API

Upload, manage, and transform video content with comprehensive media management capabilities.

For detailed documentation, see FastPix Video on Demand Overview.

Input Video

Manage Videos

Playback

Playlist

Signing Keys

DRM Configurations

Live API

Stream, manage, and transform live video content with real-time broadcasting capabilities.

For detailed documentation, see FastPix Live Stream Overview.

Start Live Stream

Manage Live Stream

Live Playback

Simulcast Stream

Video Data API

Monitor video performance and quality with comprehensive analytics and real-time metrics.

For detailed documentation, see FastPix Video Data Overview.

Metrics

Views

Dimensions

Errors

Transformations

Transform and enhance your video content with AI and editing capabilities.

In-Video AI Features

Error Handling

FastpixClient::Models::Errors::APIError is the primary error class for HTTP error responses. It has the following properties:

Property Type Description
message String Error message
status_code Integer HTTP response status code (e.g. 404)
raw_response Faraday::Response Raw HTTP response
body String HTTP body. Can be empty if no body is returned.

Example

require 'json'
require 'fastpixapi'

Models = ::FastpixClient::Models
s = ::FastpixClient::Fastpixapi.new(
  security: Models::Components::Security.new(
    username: 'your-access-token',
    password: 'your-secret-key'
  )
)

begin
  req = Models::Components::CreateMediaRequest.new(
    inputs: [
      Models::Components::PullVideoInput.new(
        type: 'video',
        url: 'https://static.fastpix.com/fp-sample-video.mp4',
      ),
    ],
    metadata: { 'key1' => 'value1' },
  )
  res = s.input_video.create_media(request: req)
  puts JSON.pretty_generate(JSON.parse(res.raw_response.body))
rescue FastpixClient::Models::Errors::APIError => e
  puts e.message
  puts e.status_code
  puts e.body
rescue StandardError
  puts res.raw_response.body.to_s if defined?(res) && res&.raw_response
end

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the server_url optional parameter when initializing the SDK client instance:

require 'json'
require 'fastpixapi'

Models = ::FastpixClient::Models
s = ::FastpixClient::Fastpixapi.new(
  server_url: 'https://api.fastpix.com/v1/',
  security: Models::Components::Security.new(
    username: 'your-access-token',
    password: 'your-secret-key'
  )
)

req = Models::Components::CreateMediaRequest.new(
  inputs: [
    Models::Components::PullVideoInput.new(
      type: 'video',
      url: 'https://static.fastpix.com/fp-sample-video.mp4',
    ),
  ],
  metadata: { 'key1' => 'value1' },
)

begin
  res = s.input_video.create_media(request: req)
  puts JSON.pretty_generate(JSON.parse(res.raw_response.body))
rescue FastpixClient::Models::Errors::APIError => e
  puts JSON.pretty_generate(JSON.parse(e.body))
rescue StandardError
  puts res.raw_response.body.to_s if defined?(res) && res&.raw_response
end

FAQ

How do I install the FastPix Ruby SDK? Add gem 'fastpixapi' to your Gemfile and run bundle install, or run gem install fastpixapi. See Install the SDK.

How do I authenticate the SDK? FastPix uses Basic Auth: pass your access token as username and your secret key as password in Models::Components::Security when constructing the client. See Initialize the FastPix client.

How do I upload a video in Ruby? Create media from a URL or a direct upload through s.input_video, for example s.input_video.create_media(request: req). See Create your first media and Available Resources and Operations.

How do I start a live stream? Use the Live API resources to create and manage streams, simulcasts, and live playback IDs. See Available Resources and Operations.

How do I get video analytics and metrics in Ruby? The Video Data API exposes metrics, views, dimensions, and errors for quality-of-experience monitoring. See Available Resources and Operations.

How do I handle API errors? Rescue FastpixClient::Models::Errors::APIError, which exposes the message, status code, body, and raw response. See Error Handling.

How do I change the API base URL? Pass a server_url when constructing the client. See Server Selection.

Which Ruby versions are supported? Ruby 3.2 and above. See Before you begin.

Is the SDK production-ready? The SDK is currently in beta; pin your gem to a specific version to avoid breaking changes between releases. See Maturity.

Is the SDK typed? Yes - it is a type-safe client generated from the FastPix API specification. See Development.

Which FastPix SDK should I use?

FastPix publishes a server SDK for every major backend language, each generated from the same API specification:

Language Repo Install
Ruby (this repo) fastpix-ruby gem install fastpixapi
Node.js / TypeScript node-sdk npm install @fastpix/fastpix-node
Python fastpix-python pip install fastpix-python
PHP fastpix-php composer require fastpix/sdk
Go fastpix-go go get github.com/FastPix/fastpix-go
Java fastpix-java io.fastpix:sdk (Maven/Gradle)
C# / .NET fastpix-sdk-csharp dotnet add package Fastpix

To upload and play the media these SDKs create, use the FastPix browser libraries: web-uploads-sdk, react-web-uploader, and web-player-component. Browse everything in the FastPix organization.

Development

This Ruby SDK is programmatically generated from our API specifications. Any manual modifications to internal files may be overwritten during subsequent generation cycles.

We value community contributions and feedback. Feel free to submit pull requests or open issues with your suggestions, and we'll do our best to include them in future releases.

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version so you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Detailed Usage

For comprehensive understanding of each API's functionality, including detailed request and response specifications, parameter descriptions, and additional examples, please refer to the FastPix API Reference.

The API reference offers complete documentation for all available endpoints and features, enabling developers to integrate and leverage FastPix APIs effectively.

About

Ruby SDK simplifies integration with the FastPix platform. This SDK is designed for secure and efficient communication with the FastPix API.

Topics

fastpixfastpix-apifastpix-rubylive-streamingon-demandsimulcastingvod

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages