Converting a file

Introduction

The conversions are performed through conversion jobs. These jobs need the following information:

  • One or more input files. It can be a singe file or a list of files you want to convert.
  • One or more conversion definitions to specify the target file formats. It is possible to specify several conversions and conversion options here, for example to create videos with different quality settings from a single input. There, you can define settings like the screen size as well.

After you have defined all parameters and started the conversion job, the API generates one or more output objects. They contain information and links to the converted files.

Send a job with remote file

In order to create a simple conversion of a file located on an external URL, the following request is made.

Example remote Conversion

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": [{
        "category": "category",
        "target": "png",
        "options": {
            <conversion options here>
        }
    }]
}

Send a job uploading a file

In order to create a simple conversion of a file located on your computer or server you will need to:

  • Send a job without any input files
  • Retrieve the server and id keys from the response
  • Concatenate the server value with /upload-file/ and the id value
  • Send a job without any input files
  • The response should contain the keys id and server
  • Retrieve the server and id keys from the response
  • Concatenate the server value with /upload-file/ and the id value

Example file upload Conversion


{
    "id": "abcdd66e-bfb6-4ef3-b443-787131bb84b3"
    ...
    ...
    "server": "https://wwwXX.api2convert.com/v2/dl/webX"
    ...
    ...
}

File Upload Job Result

This is just an example. Make sure to use the values you get in the response of the create job call.

The resulting string should look like this:

Result of the previous job


{
    "id": "xxxxxxx-027b-483e-bac9-9311fe4764b9",
    "token": "xxxxxxxee5a986b35b96c78f60eab8c2",
    "type": "job",
        "status": {
        "code": "downloading",
        "info": "The file is currently downloading from the source URL."
    },
    "errors": [],
    "process": true,
    "conversion": [
        {
            ... information about conversion ...
        }
    ],
    "input": [
        {
            ... information about the input ...
        }
    ],
    "output": [],
    "callback": "",
    "notify_status": false,
    "server": "https://www27.api2convert.com/v2/dl/web2",
    "spent": 0,
    "created_at": "2017-08-15T17:20:55",
    "modified_at": "2017-08-15T17:20:55"
}

Get the status of a job via polling

The preferred way of getting the job status is via callback.

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

To get the job's information, send a GET request to the jobs endpoint by providing the id of the job you just created.

The response you will get has the exact same structure as the response in Send a job with a remote file.

Result of the previous job

GET /v2/jobs/<your JOB ID here> HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Cache-Control: no-cache

Download the converted file

Once we know the job has been completed successfully it's time to download the result.

If you take a closer look at the data returned by the API when a job is completed, you will see an output key that will be populated with data related to the result of the conversion.

Take the uri key of each output that is present and do a GET request to download it.

{
    "id": "xxxxxxx-6f8b-4b3b-b67e-150c407614b8",
    "token": "xxxxxxx0ce224701563837758ced469a",
    "type": "job",
    "status": {
        "code": "completed",
        "info": "The file has been successfully converted."
    },
    "errors": [],
    ... extra information ...
    "output": [
        {
            "id": "xxxxxxx-46fd-4e3c-826b-db01a140dea0",
            "source": {
                "conversion": "xxxxxxx-8932-4aa8-b66c-114995edd980",
                "input": [
                    "xxxxxxx-ecb6-4ddb-b713-e314125a536e"
                ]
            },
            "uri": "https://www13.api2convert.com/v2/dl/web2/download-file/xxxxxxx-6f8b-4b3b-b67e-150c407614b8/example_small.png",
            "size": 99101,
            "status": "enabled",
            "content_type": "image/png",
            "downloads_counter": 0,
            "checksum": "33eeb8844313b7f381f844eca40ae687",
            "created_at": "2017-08-15T17:33:05"
        }
    ],
    ... extra information ...
}

Post request example

GET /v2/dl/web2/download-file/xxxxxxx-6f8b-4b3b-b67e-150c407614b8/example_small.png HTTP/1.1
Host: www13.api2convert.com
Cache-Control: no-cache

Download the converted file in a different encoding

If you need to change the encoding of the file to download, add ?encoding=base64 at the end of the URI and your downloaded file will be base64 encoded.

At the moment, just the base64 encoding is supported.

Post request example

GET /v2/dl/web2/download-file/xxxxxxx-6f8b-4b3b-b67e-150c407614b8/example_small.png?encoding=base64 HTTP/1.1

Job lifecycle and errors

To better understand how the API works, it is necessary to explain how the lifecycle of a job works.

A job can have one of the following status:

Code Description
incomplete Missing information to run the job
ready The job is ready but not marked to be processed yet
queued The file is waiting in the queue for being processed
downloading The input file you provided is currently being downloaded
pending The file is waiting in the queue to be downloaded
processing The file is currently being converted
completed The file has been successfully converted
failed The file has not been converted due to errors

Example Code

GET /v2/dl/web2/download-file/xxxxxxx-6f8b-4b3b-b67e-150c407614b8/example_small.png?encoding=base64 HTTP/1.1

Completed or failed status

Usually, the focus will be on jobs with a completed or failed status.

When the job has been completed, you can follow the instructions to download the result

In case of a failed job, you will get a failed status. It will furthermore have an errors key, where you can find a more detailed messages on what caused the job to fail. It should look similar to this:

{
    ... extra information ...
    "status": {
        "code": "failed",
        "info": "The file has not been converted due to errors."
    },
    "errors": [
        {
            "source": "input",
            "id_source": "bc6eb7a7-8c3b-49fe-9216-0eedb2e32361",
            "code": 17,
            "message": "File not found, reasons for this error could be: bucket has incorrect permissions, you sent invalid credentials, or the file is really not there"
        }
    ],
    "process": true,
    ... extra information ...
}

By default a job fails if there is an error with an input file or the conversion of one input fails. If you want to continue the job in these cases we offer two options to achieve this.
If you don't want to fail the job if parts ot the inputs can not be downloaded, set "fail_on_input_error": false.
If you don't want to fail the job on a conversion error, set "fail_on_conversion_error": false.

If you set either of these two options, your job can have warnings instead of errors. If the job does not produce any output it will fail with an according error message.

Example Job

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/audio/mp3/example.mp3"
    },
    {
        "type": "remote",
        "source": "https://some-invalid-url.com"
    }],
    "conversion": [{
        "target": "txt"
    },
    {
        "target": "aac"
    }],
    "fail_on_input_error": false,
    "fail_on_conversion_error": false
}

Completed job example

In this case the warnings in the job info look like this:

Example Job

class="   lang-json">{
    ... extra information ...
    "status": {
            "code": "completed",
            "info": "The file has been successfully converted."
    },
    "errors": [],
    "warnings": [
        {
            "source": "input",
            "id_source": "acef976e-b232-4af0-8e54-d737dbaf9746",
            "code": 1,
            "message": "The file could not be downloaded. We are unable to resolve the host address or the host is unreachable."
        },
        {
            "source": "conversion",
            "id_source": "76a84db8-4b8f-43de-9c40-e1ed4f34029a",
            "code": 6004,
            "message": "Unfortunately we can not convert your file yet from your source file format to this target file format."
        }
    ],
    "process": true,
    ... extra information ...
}