A conversion allows you to specify a set of options that will change the output of your conversion.
This, for example, allows you to turn a colourful image into black and white or resize a video.
Take the following example: We want to convert an image to png, but in addition to that, it should be monochrome.
How can you find out if this is available and what other options you have to edit your file?
There is a list of all conversions and conversion options available here: https://api.api2convert.com/v2/conversions
The list can also be filtered by target: https://api.api2convert.com/v2/conversions?target=png
The information you get looks similar to this:
{
"id":"59",
"target":"png",
"category":"image",
"options":{
... many options here ...
"color":{
"type":"string",
"enum":[
"colored",
"gray",
"monochrome",
"negate",
"1980",
"1900"
],
"default":"colored",
"description":"Color to apply the image"
},
... many more options here ...
}
}
There you see that the monochromeoption we were looking for is available.
Now we can proceed to create a job with the options that we need.
For some conversion targets we offer the option to select a public preset from us. This preset will internally set some conversion options to meet a special target device or platform. To find out which presets are available, we provide the following endpoint: https://api.api2convert.com/v2/presets
Here, you can also set some parameters to find a specific preset. You can use category,
target and filter. Filter will search the preset name and
can be a comma separated list of search terms.
E.g. https://api.api2convert.com/v2/presets?category=video&target=mp4&filter=facebook,hq
The information you get looks similar to the example code.
The result can also include your custom presets. To find out how to save your own preset have a look here.
The value you have to set for the option preset is the id. So, if you want to use the "Facebook HQ 1280x720 (HD) 25fps" preset, you set the option "preset": "5ad9f696-7930-4991-9f03-460c3d703b89".
If you combine a preset with other options of your choice, we always overwrite the preset options with the manually set options.
Now we can proceed to create a job with the options that we need.
[
{
id: "2c450e57-ef64-469d-8245-c39535994de2",
name: "Facebook HQ 1280x720 (HD) 23.976fps",
category: "video",
target: "mp4",
scope: "public"
},
{
id: "5ad9f696-7930-4991-9f03-460c3d703b89",
name: "Facebook HQ 1280x720 (HD) 25fps",
category: "video",
target: "mp4",
scope: "public"
},
...
]
To create jobs with options for the
conversions, use the options key to pass the according options and
their values.
The following request is used to convert an image with the options color
and rotate, applying the 1980 color filter and
rotating it by 180 degrees.
The following request is used to convert an mp4 with the options preset.
If a job is not yet started, you may need to patch it to modify the conversion's options. You can reach the goal by sending a conversion PATCH request to the endpoint:
/v2/jobs/<job_id>/conversions/<conversion_id>
with the new options inside the body like in the following example.
Let's assume that your job with id f496edcb-64e2-4f76-abf0-74f75338d4eb
has a conversion with id 1886af23-86ac-461e-9a86-87d018260043
that looks like the following:
"conversion": [{
"id": "1886af23-86ac-461e-9a86-87d018260043",
"target": "gif",
"category": "image",
"options": {
"download_password": null,
"allow_multiple_outputs": false,
"dpi": 300,
"width": 500,
"height": 300,
"crop_top": null,
"crop_bottom": null,
"crop_left": null,
"crop_right": null,
"crop_origin_x": null,
"crop_origin_y": null,
"crop_width": null,
"crop_height": null,
"color": "1980",
"enhance": null,
"normalize": null,
"sharpen": null,
"antialias": null,
"despeckle": null,
"equalize": null,
"deskew": null,
"rotate": null,
"preset": null,
"alpha_channel": null
},
"metadata": {},
"output_target": []
}]
Now, let's assume you want to modify the options by removing dpi, updating the image's size (width x height) and setting deskew.
Your PATCH request should look like the following:
Note that all of the other options will keep the old values, like e.g. "color": "1980".
If you send a
GET /v2/jobs/f496edcb-64e2-4f76-abf0-74f75338d4eb
request, the conversion object in the response will reflect your
PATCH like in the example code below.
Please, note that you can PATCH only the options and metadata objects of the conversions.
"conversion": [{
"id": "1886af23-86ac-461e-9a86-87d018260043",
"target": "gif",
"category": "image",
"options": {
"download_password": null,
"allow_multiple_outputs": false,
"dpi": null,
"width": 1024,
"height": 768,
"crop_top": null,
"crop_bottom": null,
"crop_left": null,
"crop_right": null,
"crop_origin_x": null,
"crop_origin_y": null,
"crop_width": null,
"crop_height": null,
"color": "1980",
"enhance": null,
"normalize": null,
"sharpen": null,
"antialias": null,
"despeckle": null,
"equalize": null,
"deskew": true,
"rotate": null,
"preset": null,
"alpha_channel": null
},
"metadata": {},
"output_target": []
}]
We offer the possibility to save a set of options for a certain target as a preset, so it can be easily used in later conversions. These presets are only visible for the user that saved them.
The following request creates a preset for a PNG conversion with the options color and rotate, and sets the name to "my preset".
To find out how to use your preset proceed to create a job with the options that we need to make use of your preset.
To get all information for one preset, send the following request:
If you want to modify a preset e.g. to set other options or a different name, you can send a patch request for the preset id you want to modify.
To delete a preset, simply send a delete request for the preset id you want to delete.