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.
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
andid
keys from the response - Concatenate the
server
value with/upload-file/
and theid
value - Send a job without any input files
- The response should contain the keys id and server
- Retrieve the
server
andid
keys from the response - Concatenate the
server
value with/upload-file/
and theid
value
{
"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:
{
"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.
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 ...
}
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.
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 |
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.
Completed job example
In this case the warnings in the job info look like this:
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 ...
}