Make your first API request

This guide will walk you through the process of interacting with the FastPix APIs by making HTTP requests.

HTTP basic auth

Each API request to FastPix requires authentication through an Access Token, comprising an ID and a secret key. The Access Token's ID serves as its username, while the secret functions as its password.

It's important to note that FastPix solely stores a secret hash, not the secret itself. If the secret key is lost, FastPix cannot retrieve it, necessitating the creation of a new Access Token. In the event of a leaked secret key, it is recommended to revoke the corresponding Access Token on the settings page: https://dashboard.fastpix.io/settings/access-tokens.

📘

PLEASE NOTE

Access to the access tokens settings page requires you to be an admin within the FastPix organization.

API requests are authenticated using HTTP Basic Auth, where the username is the Access Token ID, and the password corresponds to the Access Token secret key. Due to the adoption of Basic Authentication and the overall security practice, all API requests must be made via HTTPS (to https://api.fastpix.io).

🚧

Check for potential discrepancies in token & environments

Access tokens are specific to an environment; for instance, a development token is not valid for requests in a production setting. Make sure that the specified environment aligns with your intended use when generating an access token in FastPix.

The following is an example of authenticating a request with cURL, which automatically manages HTTP Basic Auth. Before you make the request, you’ll have to replace the Access Token ID (username) and token secret (password) in this example with your specific credentials.

curl -X POST 'https://v1.fastpix.io/on-demand'
   --user {Access Token ID}:{Secret Key} \
   -H 'Content-Type: application/json' \
   -d '{
   "inputs": [
      {
         "type": "video",
         "url": "https://static.fastpix.io/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4",
         "startTime": 0,
         "endTime": 60
      },
      {
         "type": "watermark",
         "url": "https://static.fastpix.io/watermark-4k.png",
         "placement": {
            "xAlign": "left",
            "xMargin": "10%",
            "yAlign": "top",
            "yMargin": "10%"
         }
      }
   ],
   "metadata": {
      "key1": "value1"
   },
   "createSubtitles": {
      "name": "name",
      "metadata": {
         "key1": "value1"
      },
      "languageCode": "en-us"
   },
   "accessPolicy": "public",
   "mp4Support": "capped_4k",
   "optimizeAudio": true,
   "maxResolution": "1080p"
}'

HTTP basic authentication operates by base64 encoding the username and password within an Authorization header in the request. Specifically, the header is structured as follows:

1. Concatenate the access token ID and secret using a colon (:), and then base64 encode the resulting string.
2. The value for the Authorization header comprises the string "Basic" followed by a space and the base64 encoded result from Step 1.

In the above cURL example, the cURL library automatically manages the base64 encoding and internally sets the header value. Most HTTP libraries in your server-side language will likely have a similar mechanism for handling basic authentication. You should be able to provide the username (Access Token ID) and password(Access Token secret), allowing the library to handle the header formatting details.

Access token permissions

If your requirement is to create and modify resources with FastPix, ensure that your access token has both read and write permissions. This applies to operations such as:

• Creating new assets
• Creating direct uploads
• Creating new live streams

If your code exclusively involves GET requests without creating any resources or assets, you can limit the access token to Read-only permissions.

CORS and client-side API requests

FastPix API endpoints do not incorporate CORS headers, leading to an error if attempts are made to call the FastPix API direclty from the browser. The error, commonly know as a CORS (Cross-Origin Resource Sharing) error in the browser, displays as fellows:

🚧

CORS Error in Browser

Access to XML HttpRequest at URL from origin URL has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Acces-Control-Allow-Orign' header is present on the requested resouce.

Although it might seem convenient to make API requests directly from the browser or a mobile app, but it introduces a significant security vulnerability into your application. Storing API keys on the client side means that anyone accessing your application could potentially exploit your API credentials, gaining unauthorized control over your FastPix account.

It is absolutely necessary to make sure that FastPix API credentials are never stored in a client application. All FastPix API calls should originate from a trusted server.

Instead of attempting direct API requests from the client, the recommended workflow for your application should be:

1. The client initiates a request to your server.
2. Your server, in turn, makes an authenticated API request to FastPix.
3. Any necessary information is stored in your database by your server.
4. Your server responds to the client, providing only the relevant information required by the client. For example, for live streaming, this might be the stream key for a specific stream, or for uploads, it could be the direct upload URL.

API rate limits

FastPix APIs has some rules and limits in place to keep things running smoothly. These limits apply to everyone using FastPix, not just specific groups.

Firstly, these limits help protect you and your customers from accidental mishaps. For example, they prevent you from accidently deleting all your content or racking up unexpectedly high bills if something goes wrong.

Secondly, these rules ensure that FastPix service is always available when you need it. Whether you're starting an important live stream or urgently uploading a video, these rules help make sure everything works smoothly.

🚧

Exceeding the API rate limit

If you ever try to do too much too quickly that is when the rate limit threshold is exceeded, the FastPix API will let you know with HTTP status code 429

Video API rate limits

Here's a quick breakdown of the rate limits for different activities in the Video API:

1. When you're creating new things like Assets API , Live Streams API , or Uploads API (using a POST request to https://api.fastpix.io/video/), you can do this once per second. If you need to do a few in a row, that's okay for short period surges.
2. For other actions like getting information (GET), updating things (PUT, PATCH), or deleting stuff (DELETE), you can do these up to 5 times per second. Again, surges above this limit are okay for short moments. Examples include getting list of video assets API , updating asset API , or deleting an asset API

Remember, these rules are here to keep everything running smoothly for everyone using FastPix Video!

Playback

When it comes to people watching your streams, there's no strict limit – you can have as many viewers as you want! We only ask that you give us a heads-up if you're planning a big event with over 100,000 people watching live.

Monitoring Data

If you're checking data using the Monitoring Data APIs, you can do that once per second, and if you need to check more frequently for a short time, that's okay.

General Data

For all the otherGeneral DataAPIs, like when you're getting info or making updates, you can do those up to 5 times per second. If there's a short moment where you need to do a bit more, that's fine too. Just keep in mind these limits are here to keep things smooth for everyone using FastPix!