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"
            }
        }]
    }]
}