Working with the QUE API

This page covers the QUE API at a high level. For more specific information see the API documentation below:

QUE API Documentation

Introduction

What is QUE?

QUE is the optimal data source with an API to leverage the full capabilities of Templater to produce dynamic videos.

Who is the QUE API for?

QUE is suited for video producers, motion graphics designers, and post-production pros who have reached the limits of using spreadsheets as a data source for their video automation workflows.

Components of QUE

QUE integrates four components to deliver improved scalability, security and productivity to your video production workflow:

  • Jobs
  • Campaigns
  • Satellites
  • Templates

Getting Started

You can purchase a QUE license on Dataclay's website. Once you have user access to QUE, follow this workflow:

  • Authenticate - Log in at http://que.dataclay.com and go to your Account page to generate an API token and view your API secret.
  • Sign In - You can sign in from both the QUE Dashboard and from Templater running inside of After Effects.
  • Create a Satellite - Set up satellites inside of Templater's QUE Configuration dialog which can be accessed from Templater's Preferences.
  • Create a Template - Map data to various layers in an After Effects project with Templater and use its Project Manifest dialog.
  • Create a Campaign - Create campaigns in QUE on the Campaigns tab, or by POSTing a request to the /campaigns endpoint.
  • Create Jobs - Create jobs from the Campaign view in QUE or by POSTing a request to the /jobs endpoint or use the /jobs/batch endpoint to create multiple Jobs at once.

Authenticating

Generating an API Key to access

In QUE Dash, click your avatar and select Account from the dropdown.

On the Account page, click Generate next to the API Token field to create a new key or click the copy icon to copy an existing key.

These are required to interface with the endpoints documented here. You should never share, post, or distribute your API token or secret. If you believe your token has been compromised, you should generate a new one and use the newly generated token for your app's environment.

Using Variables to Authorize in the Header

To use your authorization key in API requests to the QUE API, we suggest creating a Variable in Postman or other API development environments.

In Postman, you can create a variable in your environment variables and set the value to be the API key you generated/copied from your profile. For example, this variable could be:

{{access_token}}

In the headers, you’ll want to include an authorization key with the following value:

Bearer {{access_token}}

Alternatively, you can include the token itself in the header, but you will need to manually update the key in every endpoint whenever you generate a new key. Whereas, API calls using the variable will automatically use the saved API key, so you only have to update the key in one location.

Satellites

Satellites are unique machines running an instance of Adobe After Effects in your environment. They request data from QUE via Templater. You can specify which Satellite will process each Campaign or Job, which enables you to allocate your rendering resources efficiently.

NOTE  You must register at least one Satellite with QUE before you can create a Campaign.

Typically, a Satellite is created and authorized by a person using a video template authoring application such as Templater running in After Effects rather than interfacing with these Satellite endpoints directly. However, there are cases where you may need to manage your Satellites through these end points.

To set up a Satellite:

  1. Register a machine with QUE to create a Satellite. Use /satellites/create to do this.
  2. Authorize the machine to give it access to your QUE data. Use /satellites/auth to do this.
  3. Assign the Templater Bot to the Satellite so it can process Jobs assigned to those Satellites. To do this, click the Assign Bot button in Templater's QUE Configuration dialog, which you can access from Templater's Preferences.

NOTE  Updating or otherwise removing a Satellite outside of Templater or the QUE Dash may have an adverse effect on existing Jobs. Proceed with caution when using these endpoints.

Creating Satellites

POST 

{{host}}/api/v1/satellites/create

Creating a new Satellite requires that you choose a name and password for it. Never share this information with anyone outside of your organization. Keep these credentials somewhere private where only you can access them. You will need to use your chosen satellite name and password to authorize it.

Each Satellite you create becomes associated with your account's Organization, and each of these satellites must be uniquely named. All of your Organization's satellites must be uniquely named. If you try to create a Satellite with a name that already exists, requests to this endpoint will respond with an error.

When creating a Satellite via Templater's QUE Configuration dialog, it will use the machine's name for the satellite's name and generate a random hash for the satellite's password. These, along with properties that outline the machine's hardware and software specifications are stored in a file named satellite.json in Dataclay's application data folder (C:\ProgramData\Dataclay on Windows and /Library/Application Support/Dataclay on Mac). This file should only be edited or deleted by Templater and should never be copied or shared.

NOTE  Creating a QUE Satellite does not immediately make it possible for its machine to access your QUE data. You must also authorize the Satellite.

For more information, see the Technical API Documentation.

Templates

Templates are representations of Adobe After Effects® projects with layers mapped to static and dynamic asset data via Templater. Dynamic assets (such as text strings, audio-visual files, and color definitions) can change from one video to the next and are controlled by QUE.

NOTE  You must have at least one Template on your QUE account to create a Campaign.

Creating Templates

POST 

{{host}}/api/v1/templates

Typically, a Template is inserted into your QUE account by an artist or designer who works within their video template authoring app. For example, Templater users open the Project Manifest dialog and click its Create Manifest button to register their data-mapped After Effects project as a Template with QUE.

NOTE  You should specify a default target composition inside an After Effects project before creating its manifest to send to QUE. Learn more about specifying a default target composition inside After Effects under the Default Target from Project heading.

When users create a project manifest from Templater, a file named template-project.json is created in the same directory that contains the opened After Effects project file. Templater reads the contents of that file and uses them in the body of this request.

When an After Effects project file (.aep) is created as a Template in QUE via Templater's Project Manifest dialog, its ID is stored in the .aep's metadata (XMP). This means that no matter where you copy or share the .aep file, the QUE Template ID stays embedded in the the file and is not removed until a Templater user deletes the Template from QUE.

A successful request responds with the inserted Template.

For more information, see the Technical API Documentation.

 

Campaigns

Campaigns are collections of Jobs that keep your data organized and secure. An agency, for example, might have one campaign for each of its clients, and could grant access to a particular campaign only to users authorized to work on it.

Creating Campaigns

POST

{{host}}/api/v1/campaigns

To create a Campaign, you will need to get the IDs of an existing Template and an existing Satellite which will be used as defaults for Jobs added to the Campaign. Learn more about Campaign defaults affecting Job creation.

NOTE  To create a Campaign you must have created at least one Template and at least one Satellite in your QUE account.

For more information, see the Technical API Documentation.

Jobs

Jobs are sets of properties that can be applied to one or more Templates and can be assigned to one or more Satellites. These properties include your videos’ customization data as well as configurations for how they should render, such as quality settings and output formats. In QUE, Jobs are organized into groups called Campaigns and assigned to Satellites.

If you are coming from the world of spreadsheets or tabbed-separated value files, consider a QUE Job as a row of data. This would make a Job's property keys the column header labels in a spreadsheet, and a Job's property values the values stored in a spreadsheet row's cells.

Creating Jobs

POST

{{host}}/api/v1/jobs

Creates a new Job in the specified Campaign.

For a request to this endpoint, you can use Templater's reserved names for property key names in the body. For example, if you wanted to specify the output name for a Job, then you can use the output property in the request. If you want to set the Job's target composition you can add the target property to the body of the request.

By default, a newly created Job's render-status key is set to ready. However, you can override any of the default value settings by including those key-values within the request's body. If an aep or _satelliteId key-value is not included in the request, QUE sets the Job's aep and _satelliteId to the Campaign's default Template and Satellite values.

NOTE  NOTE You must have at least one QUE Campaign to create a Job.

For more information, see the Technical API Documentation.