> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# 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](https://github.com/FastPix/fastpix-ruby) 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](https://dashboard.fastpix.com). See [Activate your account](/getting-started/activate-your-account).

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

| SDK value  | FastPix credential |
| ---------- | ------------------ |
| `username` | Access Token       |
| `password` | Secret Key         |

> **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

```bash
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:

```bash
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.

```bash
bundle -v
```

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

```bash
gem install bundler
```

\


## Create a Ruby project

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

```bash
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:

```bash
bundle add fastpixapi
```

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

```bash
gem install fastpixapi
```

\


## Verify the SDK installation

Confirm that the gem is installed:

```bash
gem list '^fastpixapi$'
```

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

```bash
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:

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

```powershell
# 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:

```bash
# 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:

```bash
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`:

```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")
  )
)

puts "FastPix client initialized"
```

Run it:

```bash
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:

```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-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:

```bash
bundle exec ruby main.rb
```

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

```json
{
  "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`:

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

Save this value for later operations:

```text
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](https://github.com/FastPix/fastpix-ruby), with runnable code in the [examples](https://github.com/FastPix/fastpix-ruby/tree/main/examples) directory.
* **Media** (upload, manage, playback, playlists, signing keys, DRM): [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).
* **Live** (streams, simulcasts, live playback): [Live Stream API](https://fastpix.com/docs/live-stream-api/overview).
* **Video Data** (metrics, views, dimensions, errors): [Video Data API](https://fastpix.com/docs/video-data-api/overview).
* **In-video AI** (summaries, chapters, named entities, moderation): [In-Video AI](/in-video-ai/overview).

\


#### Frequently asked questions

The SDK is a type-safe Ruby wrapper around the same FastPix REST API. It handles authentication, request serialization, and response parsing for you, so you call methods like `client.input_video.create_media(...)` instead of building raw HTTP requests. Anything the SDK does, you can also do by calling the REST API directly. See [Make your first API request](#make-your-first-api-request).

It is distributed as the `fastpixapi` gem. Run `bundle add fastpixapi` in a Bundler project, or `gem install fastpixapi` if you are not using Bundler. See [Install the FastPix SDK](#install-the-fastpix-sdk).

FastPix uses HTTP Basic Authentication. Pass your Access Token as the `username` and your Secret Key as the `password` in `Models::Components::Security` when constructing the client. See [Initialize the FastPix client](#initialize-the-fastpix-client).

Create media from a URL or a direct upload through the input-video resource on the client, for example `client.input_video.create_media(...)`. See [Make your first API request](#make-your-first-api-request).

FastPix uploads are not limited by your Ruby process memory. When you pull from a URL, FastPix fetches the file directly, and when you upload from a device, the SDK gives you a signed URL that the file goes to directly, so the bytes never pass through your Ruby application. Large multi-gigabyte files upload without extra configuration. See the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

Use the Live API resources to create and manage streams, simulcasts, and live playback IDs. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-ruby) and the [Live Stream API](https://fastpix.com/docs/live-stream-api/overview).

Generate playback IDs and manage signing keys and DRM configurations through the Media API resources. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-ruby) and the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

Create the media with a private access policy, then generate a signed playback ID so only holders of a valid token can play it. For stronger protection, enable DRM on the playback ID. You revoke access by deleting the playback ID. Handle all of this through the Media API resources. See the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

The Video Data API exposes metrics, views, dimensions, and errors for quality-of-experience monitoring. See the [Video Data API](https://fastpix.com/docs/video-data-api/overview).

Rescue `FastpixClient::Models::Errors::APIError`, which exposes the message, status code, body, and raw response. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-ruby) for the error types each operation can throw.

Pass a `server_url` when constructing the client. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-ruby).

Ruby 3.2 and later. See [Before you begin](#before-you-begin).

\


## What's next

Want to go further? Browse runnable, end-to-end samples for the FastPix Ruby SDK in the [examples folder](https://github.com/FastPix/fastpix-ruby/tree/main/examples) of the GitHub repository.

\


## Release notes

For a complete history of releases, improvements, and fixes, see the [FastPix Ruby SDK CHANGELOG on GitHub](https://github.com/FastPix/fastpix-ruby/blob/main/CHANGELOG.md).