Input Types

Introduction

In addition to using a URL or uploading a file, you can specify other inputs and thus get files stored in various ways and in different sources.

We support a variety of third party cloud storage providers like Amazon S3 or Google Cloud.

Remote input type

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.

Example Code

{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/raster%20image/png/example_small.png"
    }]
}

Password protected files

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

Example Code

{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/document/pdf/example_multipage_protected.pdf",
        "credentials": {
            "decrypt_password": "online-convert.com"
        }
    }]
}

Sending only the remote Input

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>

Example Code

{
  "credentials": {
        "decrypt_password": "my_password"
    }
}

Patching the input

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

Example Code

{"process": false}

User suggested filenames

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:

Example Code

class="lang-json">{
    "input": [{
        "filename": "Product ABC123 Manual.pdf",
        "type": "remote",
        "source": "https://www.example.com/your_dynamic_url?productId=ABC123"
    }]
}

Specify a remote download engine

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:

Example Code

{
    "input": [{
        "type": "remote",
        "source": "https://www.example.com/your_dynamic_url?productId=ABC123",
        "engine": "screenshot"
    }]
}

Supported remote engines

As to better understand the different results that you may expect from the various engines, let's assume that you have a dynamic URL like the one in the example above.

If this source URL displays a full web page with the picture, description, and price of the requested productId, you may select screenshot as your engine.

You will then receive an image/screenshot of the web page. If you are interested in the full source code of the web page with all the assets, you should select website.

If the link points you directly to a PDF document for the product, file or simply auto will probably be the best choice.

The possible values for the engine are shown in the following table:

Example Code

engine description
auto We do our best to choose the best engine to download the remote content for your conversion
file The remote URL is considered as a single file with its own filename and extension
screenshot Use this engine when what you need is a screenshot of a remote web page
website When you need all the files that are used to render the remote web page
screenshot_pdf This engine downloads a website as PDF document

Post URL-generation

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.

Example Code

POST /v2/dl/web2/upload-file/39ef70ea-efc8-42a2-84dc-2090e1055077 HTTP/1.1
Host: www13.api2convert.com
x-oc-api-key: <your API key goes here>
x-oc-upload-uuid: <your random string or a full UUID>
Cache-Control: no-cache
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="decrypt_password"

this_is_a_password
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="myfile.png"
Content-Type: image/png

... contents of the file go here ...
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Amazon S3

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:

Field Description Required Default
input.type Specifies the type of input. For cloud storage always use cloud. Yes N/A
input.source Tells our servers which cloud storage provider must be contacted, in this case amazons3. Yes N/A
input.parameters.bucket Determines from which bucket our servers will get the file. Yes N/A
input.parameters.region Indicates the region configured for your bucket. A list of Amazon S3 region names can be found here. If you don't specify this field and your bucket is configured to use another region than the default, any download will fail. No eu-central-1
input.parameters.file Amazon S3 key of the file to download. Usually looks like a normal file path, e.g. pictures/mountains.jpg. Yes N/A
input.credentials.accesskeyid The Amazon S3 access key ID. Yes N/A
input.credentials.secretaccesskey The Amazon S3 secret access key. Yes N/A
input.credentials.sessiontoken Together with secretaccesskey and accesskeyid, this is used to authenticate using temporary credentials. For more information on how to generate temporary credentials please check how to install AWS CLI tool and how to do a call to AWS STS get-session-token. No N/A

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [
        {
            "target": "png"
        }
    ],
    "input": [{
        "type": "cloud",
        "source": "amazons3",
        "parameters": {
            "bucket": "your bucket name",
            "file": "path to the file you want us to download"
        },
        "credentials": {
            "accesskeyid": "your accesskey id",
            "secretaccesskey": "your secret access key"
        }
    }]
}

Google Cloud Storage

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

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

Field Description Required Default
input.type Specifies the type of input. For cloud storage always use cloud. Yes N/A
input.source Tells our servers which cloud storage provider must be contacted, in this case googlecloud. Yes N/A
input.parameters.projectid The ID of your Google Cloud project. Yes N/A
input.parameters.bucket Determines from which bucket our servers will get the file. Yes N/A
input.parameters.file Complete path to the file to download, e.g. folder-inside-bucket/image.jpeg. Yes N/A
input.credentials.keyfile Here, specify the contents of your json private key file. You can generate one following these instructions. Yes N/A

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [{
        "target": "png"
    }],
    "input": [{
        "type": "cloud",
        "source": "googlecloud",
        "parameters": {
            "projectid": "your google cloud project id",
            "bucket": "your.bucket.name",
            "file": "the complete path to the file"
        },
        "credentials": {
            "keyfile": {
                "type": "...",
                "project_id": "...",
                "private_key_id": "...",
                "private_key": "...",
                ... and more fields below ...
            }
        }
    }]
}

Microsoft Azure Blob Storage

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

Field Description Required Default
input.type Specifies the type of the input. For cloud storage always use cloud. Yes N/A
input.source Tells our servers which cloud storage provider must be contacted, in this case azure. Yes N/A
input.parameters.container The name of the container that holds your files. Yes N/A
input.parameters.file Complete path to the file to download, e.g. folder-inside-bucket/image.jpeg. Yes N/A
input.credentials.accountname Can be found in the storage account dashboard. It's the name before the blob.core.windows.net URL. Yes N/A
input.credentials.accountkey Can be found in the storage account dashboard under the Access Keys menu entry. Yes N/A

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [{
        "target": "png"
    }],
    "input": [{
        "type": "cloud",
        "source": "azure",
        "parameters": {
            "container": "the name of the container that holds your files",
            "file": "the complete path to the file"
        },
        "credentials": {
            "accountname": "the account name",
            "accountkey": "the access key of your account"
        }
    }]
}

FTP Server

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

Field Description Required Default
input.type Specifies the type of the input. For cloud storage always use cloud. Yes N/A
input.source Tells our servers which cloud storage provider must be contacted, in this case ftp. Yes N/A
input.parameters.host The URL or IP of the FTP server. Yes N/A
input.parameters.file Complete path to the file to download, e.g. `folder-ion-ftp/image.jpeg Yes N/A
input.parameters.port The port used to connect to the FTP server. No 21
input.credentials.username The username of the FTP server account. Yes N/A
input.credentials.password The password of the FTP server account. Yes N/A

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [{
        "target": "png"
    }],
    "input": [{
        "type": "cloud",
        "source": "ftp",
        "parameters": {
            "host": "host of your FTP server",
            "file": "the complete path to the file"
        },
        "credentials": {
            "username": "username",
            "password": "password"
        }
    }]
}

Base64

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.

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "conversion": [{
        "target": "png"
    }]
}

Post URL-generation

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.

Example Code

POST /v2/dl/web2/upload-base64/a6f691e2-839e-49e5-829d-dc2d97486fe1 HTTP/1.1
Host: www13.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
  "content": "data:image/gif;base64,R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
  "filename": "black-pixel"
}

Multiple base64 files at once

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.

Example Code

POST /v2/dl/web2/upload-base64/a6f691e2-839e-49e5-829d-dc2d97486fe1 HTTP/1.1
Host: www13.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

[{
  "content": "data:image/gif;base64,R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
  "filename": "black_pixel.gif"
},{
  "content": "data:text/plain;base64,dGVzdCBzdHJpbmc=",
  "filename": "example_string.txt"
}]

Input id

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:

Example Code

class="lang-json">{
    ... extra information ...
    "input": [
        {
            "id": "5e0aa023-2235-4e78-a0fc-3106b2689dd3",
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/png/example_small.png",
            "filename": "example_small.png",
            "size": 333205,
            "hash": "144979874887251a2150c5485e294001",
            "checksum": "144979874887251a2150c5485e294001",
            "content_type": "image/png",
            "created_at": "2017-08-17T16:36:44",
            "modified_at": "2017-08-17T16:36:45",
            "parameters": []
        }
    ],
    ... extra information ...
}

Creating your next job

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:

Example Code

POST /v2/jobs HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key>
Content-Type: application/json
Cache-Control: no-cache

{
    "input": [{
        "type": "input_id",
        "source": "5e0aa023-2235-4e78-a0fc-3106b2689dd3"
    }],
    "conversion": [{
        "target": "png"
    }]
}

Google Drive Picker

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"

Example Code

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": "gdrive_picker",
        "source": "put google drive picker file id here",
        "credentials": {
            "token": "put google drive picker token for the selected file here"
        },
        "content_type": "if this is a specific google document",
        "filename": "name of the input file"
    }],
    "conversion": [{
        "target": "png"
    }]
}

Modify an Input

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

Example Code

PATCH /v2/jobs/60056999-6cb9-4301-8c91-0247036f2098/input/d163a942-465d-4f0f-9d96-e05dce7bd686 HTTP/1.1
Host: api.api2convert.com
x-oc-api-key: <your API key here>
Content-Type: application/json
Cache-Control: no-cache

{
    "credentials": {
        "decrypt_password": "online-convert.com"
    }
}

Job modification API answer

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.

Example Code

{
    "id": "d163a942-465d-4f0f-9d96-e05dce7bd686",
    "type": "remote",
    "source": "https://example-files.online-convert.com/document/pdf/example_multipage_protected.pdf",
    "filename": "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:47:12",
    "parameters": [],
    "metadata": {
        "pages": "7",
        "page_size": "595 x 842 pts (a4)",
        "pdf_password_valid": true,
        "pdf_password_conversion_permission": true,
        "password_protected": true
    }
}