Skip to main content

Getting Started

The Karaoke API is a RESTful service that lets you build your own integration for Stingray Karaoke. With the APIs, you can offer consistent player functionality and continuous access to the Stingray Karaoke catalog.

To get started, you'll need to do the following:

  • Request Your API Credentials: Obtain your unique API credentials. For detailed instructions, refer to Requesting Your API Credentials.
  • Obtain a JWT: Authenticate with our authenication server. For detailed instructions, refer to Obtaining a JWT.
  • Build your Karaoke API service backend. For example endpoint requests, refer to Endpoints and Requests.

Requesting Your API Credentials​

Before you can start making API calls, you'll need to obtain your unique API credentials. These credentials are essential for authenticating with our API and ensuring secure communication between your application and our services. If you've already received your credentials from Stingray, you're all set to move on to the next step. However, if you haven't received them or are unsure about your credentials, please follow these instructions:

  1. Contact Stingray Support: Reach out to our support team here. Please provide your company and contact information, along with a brief description of how you plan to use the API.
  2. Wait for a Response: Our support team will review your request and provide you with a set of credentials, consisting of a client ID and a client secret.

Obtaining a JWT​

Once you have your credentials, the next step is to authenticate with our authentication server. This process will grant you a JSON Web Token (JWT), which is required for making API calls.

To obtain a JWT, make a POST request to https://login.stingray.com/loginapi/oauth/deviceLogin using your client ID and client secret.

Steps:

  1. Encode your client ID and client secret in Base64 format. The structure should appear as client_id:client_secret.
  2. Send a POST request to https://login.stingray.com/loginapi/oauth/deviceLogin with the necessary headers and parameters.

Headers

Content-Type: application/x-www-form-urlencoded Authorization: Basic {encoded_credentials}

Parameters

(required) deviceId: Identifier of the device accessing the API (optional) partnerId: Partner id for tracking purposes

Sample Request

curl -X POST https://login.stingray.com/loginapi/oauth/deviceLogin \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic {encoded_credentials}' \ --data-urlencode 'deviceId=myDevice'

In this sample request, replace {encoded_credentials} with the Base64 encoded string of your client ID and client secret.

Response

The response will include a JWT which you will use in the next step to authenticate with the Music API. The response structure should appear as:

{ "access_token": "your_jwt_token", "expires_in": 86400, "token_type": "Bearer" }

Service Endpoint​

The Karaoke API's base endpoint is https://karaoke-api-service-prod.stingray.com/.

Data Models​

You can access four data models using the Karaoke API:

  • Songs: Our catalog has over 140 000 songs.
  • Artists: Our catalog has over 7500 artists.
  • Party Mixes: A curated playlist of songs.
  • Filters: A data set that can be used to browse the Stingray Karaoke catalog.
note

The list of songs and their respective fields are updated daily. During the update, it is possible that a particular asset may not generate correctly and be unavailable for a day.

Endpoints and Requests​

You can access the REST Karaoke API using curl or any other HTTP client. The following are sample request examples using a REST approach:

/songs?era=80s&page=0&size=3

/songs/KAR:G:1514379,KAR:G:1185808?withPlayLink=true

/artists?size=3&page=0&starting-letter=a&sort-direction=reverse&sort-type=a-z

/artists/G:873,G:124700/songs?size=3

/artists/G:123456/

Example GET Request​

The following example request retrieves artist resources that have a starting letter value of a.
Replace {access_token} with an actual access token.

curl -X 'GET' \
  'https://karaoke-api-service-prod.stingray.com/v1/artists?starting-letter=a&sort-direction=normal&sort-type=popularity&size=10&page=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Example POST Request​

The following example request creates a play log for a specified karaoke song ID.
Replace {api_key} and {access_token} with your actual API key and access token, respectively.

curl -X 'POST' \
  'https://karaoke-api-service-prod.stingray.com/v1/play-log' \
  -H 'accept: */*' \
  -H 'X-API-KEY: {api_key}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "song_id": "KAR:G:XXXXXXX",
  "duration_played_seconds": 10
}'
note

The Karaoke API is versioned with a new release every year. To ensure the stability of your app, you must specify a supported version in the URL.