Guide

Importing files

Remote URLs, direct uploads, base64 and cloud inputs.

Inputs tell the API where to read your source files. Each entry in a job's input[] has a type and a source; some types add a few more fields. Below is a full example for every input type.

type	Use when
`remote`	The file is reachable over HTTP(S).
`upload`	You hold the bytes and upload them directly.
`base64`	Small files inlined in the request.
`cloud`	Read from S3, Azure, Google Cloud or FTP.
`gdrive_picker`	A file chosen via the Google Drive picker.
`input_id`	Reuse an input from another job.
`output`	Chain a previous job's output as a new input.

Remote URL `remote`

Point the API at a publicly reachable URL:

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

The optional engine field controls how the URL is fetched (e.g. capture a web page) — see Download engines & website capture. For password-protected sources, add credentials:

"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/archive/zip/example.zip",
  "credentials": { "decrypt_password": "hunter2" }
}]

Direct upload `upload`

Uploading is three steps. First, create the job without starting it:

curl -X POST "https://api.api2convert.com/v2/jobs" \
  -H "x-api2convert-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ]
}'

The response includes a server assigned to the job. Upload your file there as multipart form-data (field name file), at the path /upload-file/<job-id>:

curl -F "file=@photo.jpg" \
  -H "x-api2convert-api-key: <your-api-key>" \
  -H "x-api2convert-upload-uuid: <a-unique-id>" \
  "<server>/upload-file/<job-id>"

Then start the job:

curl -X PATCH "https://api.api2convert.com/v2/jobs/<job-id>" \
  -H "x-api2convert-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "process": true
}'

For large files, our PHP SDK handles chunked uploads for you.

Base64 `base64`

Inline a small file directly in the request as a base64 string:

"input": [{
  "type": "base64",
  "source": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago...",
  "filename": "document.pdf"
}]

Cloud storage `cloud`

Set type: "cloud" and put the provider name in source, then supply that provider's parameters and credentials.

Amazon S3

"input": [{
  "type": "cloud",
  "source": "amazons3",
  "parameters": { "bucket": "my-bucket", "file": "in/photo.jpg", "region": "eu-central-1" },
  "credentials": { "accesskeyid": "<your-access-key-id>", "secretaccesskey": "<your-secret-access-key>" }
}]

region is optional and defaults to eu-central-1 — but it must match the region your bucket actually lives in, or the download fails.

Azure Blob Storage

"input": [{
  "type": "cloud",
  "source": "azure",
  "parameters": { "container": "my-container", "file": "in/photo.jpg" },
  "credentials": { "accountname": "<your-account-name>", "accountkey": "<your-account-key>" }
}]

Google Cloud Storage

"input": [{
  "type": "cloud",
  "source": "googlecloud",
  "parameters": { "projectid": "my-project", "bucket": "my-bucket", "file": "in/photo.jpg" },
  "credentials": { "keyfile": { "type": "service_account", "project_id": "my-project", "private_key": "<your-private-key>", "client_email": "<your-service-account-email>" } }
}]

Pass keyfile as the full service-account JSON object, inlined — not as a string containing JSON.

FTP

"input": [{
  "type": "cloud",
  "source": "ftp",
  "parameters": { "host": "ftp.example.com", "file": "/in/photo.jpg" },
  "credentials": { "username": "<your-ftp-username>", "password": "<your-ftp-password>" }
}]

Putting it together — a complete job that converts a file straight out of Amazon S3, with no upload on your side. The other providers work the same way: swap source, parameters and credentials for the ones listed above.

curl -X POST "https://api.api2convert.com/v2/jobs" \
  -H "x-api2convert-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
        {
            "type": "cloud",
            "source": "amazons3",
            "parameters": {
                "bucket": "my-bucket",
                "file": "in/photo.jpg",
                "region": "eu-central-1"
            },
            "credentials": {
                "accesskeyid": "<your-access-key-id>",
                "secretaccesskey": "<your-secret-access-key>"
            }
        }
    ],
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ],
    "process": true
}'

Cloud inputs go through the full job payload, so the SDKs expose them via jobs().create() rather than the one-line convert() helper. Pair this with an output target to read and write your own storage — the file never touches your machine.

Google Drive `gdrive_picker`

For files chosen with the Google Drive picker, use the Drive file id as source and pass an OAuth access token in credentials:

"input": [{
  "type": "gdrive_picker",
  "source": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "filename": "report.pdf",
  "credentials": { "token": "<google-oauth-access-token>" }
}]

Reuse another job's input `input_id`

Reference an input you already created on another job by its id — no need to re-upload or re-download:

"input": [{
  "type": "input_id",
  "source": "<input-id-from-another-job>"
}]

Chain a previous output `output`

Feed the output of a finished job straight into a new one — useful for multi-step pipelines (e.g. convert, then compress):

"input": [{
  "type": "output",
  "source": "<output-id-from-another-job>"
}]

Remote URL remote

Direct upload upload

Base64 base64

Cloud storage cloud