Converting a file

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

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

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:

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.

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 ...
}

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.

Before a job is started, it is possible to patch any of the following elements: process, conversion, limits, input, callback, notify_status and after the job is successfully completed, the output element can be patched too.
To patch an element you have to send a PATCH HTTP request to the relevant endpoint
(e.g. /jobs/{job_id}/conversion)

The schema of all patch endpoints with all the available parameters to be set is located here: https://api.api2convert.com/v2/schema

At any time, a job can be deleted by sending a DELETE call to /v2/jobs/{job_id} endpoint.

In the same way, it is possible to delete any other job's object by addressing it directly.
E.g. by sending a DELETE call to /v2/jobs/{job_id}/input/{input_id} endpoint

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:

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.

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