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:

• Get an API key. Your Stingray representative provides you with a unique API key than can be used to generate access tokens. For more information, refer to Authenticating Your Karaoke API Service.
• Generate an access token. Using the provided API key, you can generate access tokens for making calls to the Karaoke API. For detailed instructions on how to generate access tokens, refer to Generating Access Token.
• Build your Karaoke API service backend. For example endpoint requests, refer to Endpoints and Requests.

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.

Authenticating Your Karaoke API Service

All Karaoke API queries require a valid Stingray API key and access token. While the API key is provided by Stingray, access tokens are generated using the Login endpoint.

Parameter	Description	Type
x-api-key	An x-api-key must be included in the header for every call. This key is provided by Stingray, and is unique for each partner.	String
Bearer Token	User-generated access token using OAuth 2.0.	String

note

Cross-Origin Resource Sharing (CORS) is disabled for all endpoints.

Generating Access Tokens

A Bearer Token is set in the Authorization header of every HTTP request. The process flow for generating the token is as follows:

1. Submit login information from the client application to the client server.
2. The client server passes the API key and authenticates with the Stingray Karaoke API.
3. Create a POST login request. The following device login information is included in the request body:

// Request body
{
  "client_ip": "0.0.0.0", // Where the call is coming from. (Optional)
  "language_code": "en", // Language code.
  "device_id": "karaoke_api_swagger", // Unique ID for the device using the API.
  "country_code": "CA", // 2 letter ISO 3166-1 country code.
  "account_id": "123" // The account profile ID. (Optional)
}

4. Once authenticated, the Stingray Karaoke API returns a token to the client server.
5. The client server returns the Bearer Token to the client application.
6. The client application uses the token for calls to the Stingray Karaoke API for the session.

Bearer Token Example

In the following sample header code, the token has a value of foo and the API key is bar.

Authorization: Bearer foo
X-API-KEY: bar

The curl sample code would be as follows:

curl -X GET "https://karaoke-api-service-prod.stingray.com/v1/artists" -H "accept: application/json" -H "Authorization: Bearer foo" -H "X-API-KEY: bar"

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.