This section will help you get started with Pixlee Content API.



The Pixlee Content API is designed to allow developers to freely consume and submit content. We expose a flexible and rich amount of media metadata to allow customization of beautiful, personalized experiences full of user-generated photos and videos from fans and customers.

For 95% of use-cases, you will want to be referencing the Get Approved Media from an Album endpoint. This will help you get content from albums of your choice or content related to specific products, and is the most commonly used endpoint.

🚧

Limitations

This API is focused on the programmatic consumption and submission of content out of and into Pixlee, respectively, and is intended to be used by advanced users. It is not meant for accessing analytics, documentation for which can be found here.

Getting Started

  • Get your keys: Go to the API tab under account settings from inside Pixlee. Your API Key and Secret Key are disclosed there.
  • Access: Access the API from anywhere. We've enabled CORS so you can access endpoints just as easily with XHR as with cURL.
  • That's it!

Important Notes

  • All response objects are accessible under the 'data' key in the response envelope.

  • POST payloads always include content header "Content-Type: application/json".

  • By default, endpoints under distillery.pixlee.co are CDN cached by their full URL, with an expiry of 2 minutes. This helps to ensure speedy responses while keeping data relatively fresh.

  • A timestamp parameter can be added to refresh this cache on demand, using the parameter &unique_id=NUMERIC_TIMESTAMP.

Authentication

All POSTs will need to be accompanied with an HMAC-SHA1 signature. To generate the signature, run your payload through HMAC-SHA1, using your secret key to sign (this can be found in your Pixlee account settings), convert to Base64, and send the result in the header "Signature": "result".

Generally your payload will be in JSON. When calculating the signature for the payload, convert your payload to JSON, which removes unnecessary spaces and line breaks. Our signature calculation is given below in Scala:

private def calculateSignature (secret: String, toEncode: String): String = {
    /**
      * Calculate the HMAC for the specified data and the supplied secret
    */
    val HMACSHA1 = "HmacSHA1"
    val signingKey = new SecretKeySpec(secret.getBytes(), HMACSHA1)
    val mac = Mac.getInstance(HMACSHA1)
    mac.init(signingKey)
    val rawHmac = mac.doFinal(toEncode.getBytes())
    new String(Base64.encodeBase64(rawHmac))
  }

You can sanity check your key generation with https://www.liavaag.org/English/SHA-Generator/HMAC/

As an example, say that your JSON payload looks like

{
  "album_id": 12345,
  "title": "Testing Photo Upload",
  "approved": true,
  "email": "[email protected]",
  "username": "Submitter Person",
  "photo_uri": "https://example.com/test.jpg"
}

After JSON formatting, it will look like

{"album_id":12345,"title":"Testing Photo Upload","approved":true,"email":"[email protected]","username":"Submitter Person","photo_uri":"https://example.com/test.jpg"}

Given a secret key of "ABCDEFG", submitting this string here: https://www.liavaag.org/English/SHA-Generator/HMAC/ and choosing Input type TEXT, Key type TEXT, SHA-1 variant, and Base-64 output gives:

epBvDlHbQho/rNDdQVJowWMtGsg=

As our final signature output.

Then your final cURL will look like:

curl -X POST \
                              'https://distillery.pixlee.co/api/v2/media?api_key=<MY_PRIVATE_API_KEY>' \
                              -H 'Content-Type: application/json' \
                              -H 'Signature: epBvDlHbQho/rNDdQVJowWMtGsg=' \
                              -d '{"album_id":12345,"title":"Testing Photo Upload","approved":true,"email":"[email protected]","username":"Submitter Person","photo_uri":"https://example.com/test.jpg"}'

❗️

WARNING

If you are using this API to create widget/display experiences on your website, you must also make sure to implement the engagement section of the conversion analytics.

Not doing so will cause conversion analytics to become inaccurate, as people may deserve to be attributed with Pixlee engagement, but will not.

The guide for doing so is available here