Execute Combination

Executes a Combination

The Execute Combination API allows you to run a Combination. You can use this API to provide the input and input parameters for a Combination, and get the Combination response.

Quick Start

To run a Combination, you must specify the Combination name in the combination parameter. You can specify a public Combination, or one that you have created by using the Combinations user interface.

/1/api/[async|sync]/executecombination/v1?combination=helloworld

You specify the input parameters for the Combination by using the parameters, file, and file_parameters parameters.

The parameters parameter accepts an array of JSON objects that define the Combination parameters and their values. You can use this for input parameters that require a simple string or numeric value. The JSON array must have the following format:

[
   {
      "name": "parametername1",
	  "value": "parametervalue1"
   },
   {
      "name": "parametername2",
	  "value": "parametervalue2"
   }
]

For example:

/1/api/[async|sync]/executecombination/v1?combination=mycombination&parameters=[{"name":"language","value":"eng"},{"name":"text","value":"some input text"}]

The file and file_parameters parameters allow you to provide file inputs for your Combinations. The file parameter specifies the file that you want to use, and file_parameters specifies the corresponding Combination input parameter that you want to use the file for. Both parameters accept an array of values. Each file value must have a corresponding file_parameters value, specified in the corresponding order.

The following example uses a POST request to upload two files. It uses myvideo.mp4 as the input for the video_file Combination input, and myimage.jpg as the input for the image_file Combination input.

curl -X POST http://api.havenondemand.com/1/api/async/executecombination/v1 --form "combination=mymediacombination" --form "file_parameters=video_file" --form "file_parameters=image_file" --form "file=@myvideo.mp4" --form "file=@myimage.jpg"

Synchronous
https://api.havenondemand.com/1/api/sync/executecombination/v1
Asynchronous
https://api.havenondemand.com/1/api/async/executecombination/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
combination
resource The name of the Combination that you want to run.
Optional
Name Type Description
major_version
integer Major version of the combination to execute.
parameters
array<json> A JSON object that defines the parameter names and values that you want to use as input values for the Combination. Default value: [].
file_parameters
array<string> The input parameters in the Combination to send the specified files to. Each value for file_parameters must have a corresponding value in file. Default value: [].
file
array<binary> One or more files to use as input for the Combination. Each value for file must have a corresponding value in file_parameters. Default value: [].

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Execute Combination Response {
results ( array[Results] ) The results of the Combination execution.
}
Execute Combination Response:Results {
name ( string )
value ( object )
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "type": "object",
    "required": [
        "results"
    ],
    "additionalProperties": false,
    "properties": {
        "results": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "name",
                    "value"
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "value": {}
                }
            }
        }
    }
}


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.