Importing files

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-oc-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-oc-api-key: <your-api-key>" \
  -H "x-oc-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-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "process": true }'

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" },
  "credentials": { "accesskeyid": "AKIA...", "secretaccesskey": "..." }
}]

Azure Blob Storage

"input": [{
  "type": "cloud",
  "source": "azure",
  "parameters": { "container": "my-container", "file": "in/photo.jpg" },
  "credentials": { "accountname": "myaccount", "accountkey": "..." }
}]

Google Cloud Storage

"input": [{
  "type": "cloud",
  "source": "googlecloud",
  "parameters": { "projectid": "my-project", "bucket": "my-bucket", "file": "in/photo.jpg" },
  "credentials": { "keyfile": "<service-account-JSON>" }
}]

FTP

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

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