Your email address belongs to a school and you are eligible for a free educational premium account.
Learn more

Advanced API Calls

Get a job status via callback

Once a job is created, you need to know if the job failed, was completed successfully or if it is still processing.

By sending a callback url together with the job, you will be notified instantly when the job finished either with the status failed or completed.

If you want to receive a callback with every job status change (e.g. ready, processing in addition to failed or completed), set the flag notify_status to true.

The information received in your callback script has the same structure as the response in Send a job with a remote file.

Example Code

POST /v2/jobs HTTP/1.1
Host: https://api.api2convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    }],
    "conversion": [{
        "target": "png"
    }],
    "callback": "<put your callback url here>",
    "notify_status": false
}

Example of a simple callback endpoint

Following, you can find a very simple callback example code in PHP.

It writes the content of the callback as a human readable array in a plain text file (setting the job's Id and Status as the filename) inside the script's directory.

This way, it will be easy for you to debug all of the possible status contents by simply setting "notify_status": true in your JSON API call.

Example Code

<?php
$job        = file_get_contents('php://input');
$jobAsArray = json_decode($job, true);

if (empty($jobAsArray['id'])) {
    file_put_contents(
        'callback_errors.log',
        'Invalid callback received. Content: ' . var_export($job, true) . PHP_EOL,
        FILE_APPEND
    );

    exit;
}

$filename = sprintf('%s_%s.txt', $jobAsArray['id'], $jobAsArray['status']['code']);
file_put_contents($filename,  print_r($jobAsArray, true));

Create jobs dynamically

This is especially interesting if you have an application that uses our API. An application can have different steps where one can upload files or provide URLs, or even a step where one selects conversion options.

Lets assume an application with the following structure:

  1. A user's actions leads to the creation of a job
  2. User is able to define different conversions
  3. User is able to specify which inputs are wanted

In this case, a job can be created step by step, defining everything needed in each step.

Create jobs dynamically step #1

The 1st step is to create the job and save the id or token.

A job can be created providing the field process with the value false, so the job will not start processing even though it has the required data.

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "process": false
}

Create jobs dynamically step #2

Following that, the 2nd step is to take the conversion(s) defined by the user and feed them to our API using the POST /v2/jobs/{id}/conversions endpoint.

Example Code

POST /v2/jobs/8c267416-25dc-4298-8a26-b48f7eaa8000/conversions HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "target": "png"
}

Create jobs dynamically step #3

Lastly, for the 3rd step, take the input(s) defined by the user and feed them to our API using the POST/v2/jobs/{id}/input endpoint.

Example Code

POST /v2/jobs/8c267416-25dc-4298-8a26-b48f7eaa8000/input HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "type": "remote",
    "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
}

Create jobs dynamically with more than one input

If you have more than one input to send in the same POST request, you can define them inside an array as in the following example:

Example Code

POST /v2/jobs/8c267416-25dc-4298-8a26-b48f7eaa8000/input HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

[{
  "type": "remote",
  "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
},{
  "type": "remote",
  "source": "https://example-files.online-convert.com/raster%20image/png/example_small.png"
}]

Process dynamic jobs

  • After these steps, the job is ready to be processed. Thus, issue a PATCH request to the /jobs/{id} endpoint by sending the process field with the value true.
  • Alternatively, a callback parameter with the URL to a previously set up callback script that will handle the information of the completed job could also be set here.
  • After this, if no callback URL has been passed, it's possible to check the status of the job via polling.

Example Code

PATCH /jobs/8c267416-25dc-4298-8a26-b48f7eaa8000 HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "process": true
}

Amazon S3

To allow our servers to download files directly from the Amazon S3 storage, the following permissions are required:

  • s3:GetObject
    • Used to download a file
  • s3:PutObject
    • Used to store a file
  • s3:PutObjectAcl
    • Used to grant different Access Control List (ACL) values when storing a file

Below you can find a list with the fields that are accepted in this input type:

Field Description Required Default
input.type Specifies the type of input. For cloud storage always use cloud. Yes N/A
input.source Tells our servers which cloud storage provider must be contacted, in this case amazons3. Yes N/A
input.parameters.bucket Determines from which bucket our servers will get the file. Yes N/A
input.parameters.region Indicates the region configured for your bucket. A list of Amazon S3 region names can be found here. If you don't specify this field and your bucket is configured to use another region than the default, any download will fail. No eu-central-1
input.parameters.file Amazon S3 key of the file to download. Usually looks like a normal file path, e.g. pictures/mountains.jpg. Yes N/A
input.credentials.accesskeyid The Amazon S3 access key ID. Yes N/A
input.credentials.secretaccesskey The Amazon S3 secret access key. Yes N/A
input.credentials.sessiontoken Together with secretaccesskey and accesskeyid, this is used to authenticate using temporary credentials. For more information on how to generate temporary credentials please check how to install AWS CLI tool and how to do a call to AWS STS get-session-token. No N/A

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [
        {
            "target": "png"
        }
    ],
    "input": [{
        "type": "cloud",
        "source": "amazons3",
        "parameters": {
            "bucket": "your bucket name",
            "file": "path to the file you want us to download"
        },
        "credentials": {
            "accesskeyid": "your accesskey id",
            "secretaccesskey": "your secret access key"
        }
    }]
}

User suggested filenames

Filenames can be specified as described in the section for remote inputs

Google Cloud Storage

To allow our servers to save files on a Google Cloud Storage, follow these instructions:

Below you can find a list with the fields accepted in this output target:

Field Description Required Default
output_target.type Specifies the type of output target, in this case googlecloud. Yes N/A
output_target.parameters.projectid The ID of your Google Cloud project. Yes N/A
output_target.parameters.bucket Determines to which bucket our servers upload the file. Yes N/A
output_target.parameters.file Complete path to where the file will be uploaded, e.g. folder-inside-bucket/image.jpeg. Yes N/A
output_target.credentials.keyfile Here, specify the contents of your json private key file. You can generate one following these instructions. Yes N/A

Please note that in some circumstances (e.g. already existing filename on the cloud) the upload can be refused. For these reasons, it's highly recommended to upload converted files in new directories.

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    }],
    "conversion": [{
        "category": "image",
        "target": "png",
        "output_target": [{
            "type": "googlecloud",
            "parameters": {
                "projectid": "your project id",
                "bucket": "your bucket name",
                "file": "the complete path to where you want to store the file"
            },
            "credentials": {
                "keyfile": {
                    "type": "...",
                    "project_id": "...",
                    "private_key_id": "...",
                    "private_key": "...",
                    ... and more fields below ...
                }
            }
        }]
    }]
}

Microsoft Azure Blob Storage

To allow our servers to save files on a Microsoft Azure Blob Storage, the following parameters to send the request are available:

Field Description Required Default
output_target.type Specifies the type of output target, in this case azure. Yes N/A
output_target.parameters.container The name of the container that will contain the uploaded files. Yes N/A
output_target.parameters.file Complete path to where the file will be uploaded, e.g. folder-inside-container/image.jpeg. Yes N/A
output_target.credentials.accountname Can be found in the storage account dashboard. It's the name before the blob.core.windows.netURL. Yes N/A
output_target.credentials.accountkey Can be found in the storage account dashboard under the Access Keys menu entry. Yes N/A

Please note that in some circumstances (e.g. already existing filename on the cloud) the upload can be refused. For these reasons, it's highly recommended to upload converted files in new directories.

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    }],
    "conversion": [{
        "target": "png",
        "output_target": [{
            "type": "azure",
            "parameters": {
                "container": "the name of your container",
                "file": "file-will-be-uploaded/here.png"
            },
            "credentials": {
                "accountname": "your account name",
                "accountkey": "your account key"
            }
        }]
    }]
}

FTP Server

To allow our servers to upload files directly to an FTP server, the following parameters to send the request are available:

Field Description Required Default
output_target.type Specifies the type of output target, in this case ftp. Yes N/A
output_target.parameters.host The URL or IP of the FTP server. Yes N/A
output_target.parameters.file Complete path to where the file will be uploaded, e.g. folder-in-ftp/image.jpeg. Yes N/A
output_target.parameters.port The port used to connect to the FTP server. No 21
output_target.credentials.username The username of the FTP server account. Yes N/A
output_target.credentials.password The password of the FTP server account. Yes N/A

Please note that in some circumstances (e.g. already existing filename on the server) the upload can be refused. For these reasons, it's highly recommended to upload converted files in new directories.

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    }],
    "conversion": [{
        "target": "png",
        "output_target": [{
            "type": "ftp",
            "parameters": {
                "host": "your ftp server host",
                "file": "file-will-be-saved/here.png"
            },
            "credentials": {
                "username": "your ftp server username",
                "password": "your ftp server password"
            }
        }]
    }]
}

Limits

Your API key has constraints that determine the capabilities available to you based on the contract you have in place.
These restrictions typically pertain to computational time usage limits per conversion or maximum input file size, among others.
These constraints can be further customized using the limits object within the job's JSON request.
The following parameters are available for sending the request:

Object Section Constraints Description
limits job max_conversion_minutes Set the maximum conversion minutes that can be spent by the job.
max_inputs Set the maximum number of inputs accepted by the job.
max_process_time Set the maximum processing time, in seconds, for the job.
input max_file_size Set the maximum file size for the job inputs.
output max_downloads Set how many times a converted file can be downloaded.

It is important to note that the fail_on_conversion_error boolean value may impact the functionality of the limits.

The example shows a job that is being sent with a single image as the common input and three separate targets, allowing you to convert the image into different formats using just one job.
If you wish to limit the number of conversion minutes used, you can set the max_conversion_minutes limit.
However, the behavior may vary based on the value of fail_on_conversion_error, as described in the table below:

fail_on_conversion_error max_conversion_minutes time spent expected behaviour
true|false 4 3 Conversion is done and 3 conversion minutes are deducted from your account.
true 2 3 The time spent is more than the allowed one. Conversion fails and no conversion minutes are deducted from your account.
false 2 3 The time spent is more than the allowed one, but you choose to not fail the conversion. Conversion partly succeeds and the conversions' outputs that first reached the max allowed of 2 spent minutes are present. Just 2 conversion minutes are deducted from your account.

Example Code


{
  "input": [{
    "type": "remote",
    "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
  }],
  "conversion": [{
    "target": "png"
  },{
    "target": "bmp"
  },{
    "target": "gif"
  }],
  "limits": {
      "job": {
          "max_conversion_minutes": 2
      }
  },
  "fail_on_conversion_error": false
}