Input Types

The following code specifies a remote input file provided via URL.

This is the simplest way of specifying an input file. Define the type field as remote and specify the URL of the file you want to convert in the source.

If the input is a password protected file (e.g. pdf, zip, ...) you can specify this as following:

It is also possible to send just the remote input like in the first example and adding the password in a second step. This is done by simply sending a PATCH request to the following endpoint:

/jobs/<job_id>/input/<input_id>

In order to patch the input, the job should not be started yet. This means it should be created using

In some use cases it might be desirable to specify the name of the output file instead of using the original file name.

One such example is to rename image files with a generic name like DSC_0013.JPG to a more meaningful name like Holiday 2018_0013.png during the conversion.

A different example are dynamically generated urls like ?productId=ABC123 in which case the output filename can be set to e.g. Product ABC123 Manual.pdf.

If you are unsure about the format of your file, just send the name without the extension. It will automatically be added by us.

In order to specify the new filename you have to send the file like in the following example:

Depending on the remote input URL and on the desired target, we do our best to guess what the expected result will be like.

Sometimes our best guess is not as you may expect for your specific needs. Thus, you can specify a different remote download engine that fits your task better. Consider the example below:

You have to do a POST request to it.

The field file is where you put the contents of the file you want to send.

The optional field decrypt_password is where you put the password to open a password protected file.

Once the file is uploaded, the job will continue its lifecycle, start processing the conversion and eventually finish.

Please note that, even if not mandatory, it's highly recommended to set a unique random string for each file that you upload. This can prevent conversion problems in some corner cases. You don't need to send a full UUID, a short random string should be enough.

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

• 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:

To allow our servers to download files directly from the Google Cloud Storage, follow these instructions:

• Generate a json private key file following these instructions. Its contents will be needed later.
• Create a project following these instructions.
• Create a bucket which contains the files that you want to download following these instructions.

Below you can find a list with the fields accepted in this input type:

To allow our servers to download files directly from the Microsoft Azure Blob Storage, the following parameters to send the request are available:

To allow our servers to download files directly from an FTP server, the following parameters to send the request are available:

To send a base64 input, the following is required:

• Send a job without any input files
• The response should contain the keys id and server

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

• Retrieve the server and id keys from the response
• Concatenate the server value with /upload-base64/ and the id value

The resulting string looks like this:

https://wwwXX.api2convert.com/v2/dl/webX/upload-base64/abcdd66e-bfb6-4ef3-b443-787131bb84b3

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

After generating the URL, do a POST request to it.

The form has to contain the following fields:

• content: The base64 encoded data
• filename: This parameter is optional. If not specified, the file will be named "output".

Once the base64 data is sent, the job will continue its lifecycle, start processing the conversion and eventually finish.

If you want to send more than one base64-encoded file at once, you can send them inside an array as shown in the following example.

Please note that the max size of the JSON body should not exceed 1 GB.

This type of input allows you to use an input from a previous conversion again.

This is only possible if you are the creator of the job the input_id is taken from.

Advantages of using this input type:

• You can avoid uploading a file twice
• Our servers can avoid downloading a file a second time from the URL you supplied
  • This is especially useful for big files

Once you create a job and it is finished, you receive data similar to this:

Now, take the value of the id field. When creating your next job, add an input of type input_id and in the source field, specify the contents you retrieved from the previous input id field. Consider the following request:

Google Drive picker allows you to access files stored in a Google Drive account. You can find more information about this one the official page.

Adding a new source file of type gdrive_picker is done by using the following parameters:

• type
  • Specifies that the Google Drive picker is used as an input
• source:
  • Must contain the "FILE ID" given back by the Google Drive picker
• credentials:
  • Must be an array containing the credentials for the selected file
  • At the moment, only the "token" field inside it is required
  • The "token" field is returned by the Google Drive picker when a file is selected
• content_type:
  • Mandatory when selecting a Google Document
  • Can be left empty if selecting any other kind of file (e.g. pdf, png, zip, ...)
• filename:
  • The file name of the Google Drive picker file
  • If this field is not sent, the file will be downloaded using the name "output"

If a job is not yet started, you may need to patch it to modify the inputs. You can reach the goal by sending an input PATCH request to the endpoint:

/v2/jobs/<job_id>/input/<input_id>

with the new data inside the body like in the following example.

Let's assume that your job with id 60056999-6cb9-4301-8c91-0247036f2098 has an input with id d163a942-465d-4f0f-9d96-e05dce7bd686 that looks like the following example.

As you can see in the metadata section, the PDF is password protected, so we cannot process it. At this point, you can still add the password before starting the conversion by sending a PATCH request as in the example.

As you can see in the metadata section, the PDF is password protected, so we cannot process it. At this point, you can still add the password before starting the conversion by sending a PATCH request like the following:

"input": [{
    "id": "d163a942-465d-4f0f-9d96-e05dce7bd686",
    "type": "remote",
    "source": "https://example-files.online-convert.com/document/pdf/example_multipage_protected.pdf",
    "size": 1096348,
    "hash": "e84a82fb5f42391c57d9411b21671a87",
    "checksum": "e84a82fb5f42391c57d9411b21671a87",
    "content_type": "application/pdf",
    "created_at": "2018-10-02T08:45:21",
    "modified_at": "2018-10-02T08:45:22",
    "parameters": [],
    "metadata": {
        "pdf_has_user_password": true,
        "password_protected": true
    }
}]

If the password is the right one, you will immediately receive the answer from the API which should look like the following.

As you can see, the metadata now contains more useful information, like the number of pages and the size, that proof that we can now access and process the file.