Upload a large file using multipart upload

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "large-file.pdf",
  "fileType": "application/pdf",
  "fileSize": 150.5,
  "partSizeLimit": 10,
  "isSplit": false,
  "isSplitExcel": false,
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false,
  "pageCount": 50,
  "apiRequestId": "my-batch-request-123",
  "retainOriginalZipFileName": false
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/upload/multipart"

payload = {
    "fileName": "large-file.pdf",
    "fileType": "application/pdf",
    "fileSize": 150.5,
    "partSizeLimit": 10,
    "isSplit": False,
    "isSplitExcel": False,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": False,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "mammals/walrus",
    "isEphemeral": False,
    "pageCount": 50,
    "apiRequestId": "my-batch-request-123",
    "retainOriginalZipFileName": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileName: 'large-file.pdf',
    fileType: 'application/pdf',
    fileSize: 150.5,
    partSizeLimit: 10,
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
    destinationPath: 'mammals/walrus',
    isEphemeral: false,
    pageCount: 50,
    apiRequestId: 'my-batch-request-123',
    retainOriginalZipFileName: false
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/upload/multipart",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'large-file.pdf',
    'fileType' => 'application/pdf',
    'fileSize' => 150.5,
    'partSizeLimit' => 10,
    'isSplit' => false,
    'isSplitExcel' => false,
    'callbackURL' => 'https://example.com/callback',
    'ocrModel' => 'Beethoven_ENG_O5.6',
    'schemaLocking' => false,
    'directoryId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'destinationPath' => 'mammals/walrus',
    'isEphemeral' => false,
    'pageCount' => 50,
    'apiRequestId' => 'my-batch-request-123',
    'retainOriginalZipFileName' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/files/upload/multipart"

	payload := strings.NewReader("{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/files/upload/multipart")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/files/upload/multipart")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "upload_aws_xyz789",
  "key": "org_123/workspace_456/device/file_abc/document.pdf",
  "s3Path": "s3://bucket/org_123/workspace_456/device/file_abc/document.pdf",
  "partSize": 6291456,
  "totalParts": 2,
  "totalSize": 9123430,
  "presignedUrls": [
    {
      "partNumber": 1,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 0,
      "endByte": 6291455,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123429,
      "size": 2831974
    }
  ],
  "uploadId": "file_abc123xyz",
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false
}

Endpoints

Upload a large file using multipart upload

Initiate a multipart upload for large files (typically >100MB). This will return presigned URLs for each part.

Each presigned URL is valid for 900 seconds (15 minutes) and can be used multiple times.

The workflow is:

Call this endpoint to get presigned URLs for each part
Upload each part to its respective presigned URL using PUT requests
Call the complete multipart upload endpoint with all part ETags

The input should contain:

fileName: the name of the file to be uploaded
fileType: the MIME type of the file
fileSize: the size of the file in MB
partSizeLimit: (optional) the size limit for each part in MB
isSplit: whether the file should be split after upload (optional, default: false)
isSplitExcel: whether to split Excel files by worksheets (optional, default: false)
callbackURL: the url that will be called after processing (optional)
ocrModel: the OCR model to use (optional)
schemaLocking: whether the schema should be locked (optional)
directoryId: the directory id where the file should be uploaded (optional)
destinationPath: slash-delimited folder path where the file should be placed (e.g. “mammals/walrus”). Folders are auto-created if they do not exist. Can be used together with directoryId (optional)
isEphemeral: whether the file and all related data should be deleted after the file is processed, must be one of true or false (optional, default: false)
pageCount: page count of the file, used for early validation against page limits (optional)

POST

prod

files

upload

multipart

Upload a large file using multipart upload

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/files/upload/multipart \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileName": "large-file.pdf",
  "fileType": "application/pdf",
  "fileSize": 150.5,
  "partSizeLimit": 10,
  "isSplit": false,
  "isSplitExcel": false,
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false,
  "pageCount": 50,
  "apiRequestId": "my-batch-request-123",
  "retainOriginalZipFileName": false
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/files/upload/multipart"

payload = {
    "fileName": "large-file.pdf",
    "fileType": "application/pdf",
    "fileSize": 150.5,
    "partSizeLimit": 10,
    "isSplit": False,
    "isSplitExcel": False,
    "callbackURL": "https://example.com/callback",
    "ocrModel": "Beethoven_ENG_O5.6",
    "schemaLocking": False,
    "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
    "destinationPath": "mammals/walrus",
    "isEphemeral": False,
    "pageCount": 50,
    "apiRequestId": "my-batch-request-123",
    "retainOriginalZipFileName": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileName: 'large-file.pdf',
    fileType: 'application/pdf',
    fileSize: 150.5,
    partSizeLimit: 10,
    isSplit: false,
    isSplitExcel: false,
    callbackURL: 'https://example.com/callback',
    ocrModel: 'Beethoven_ENG_O5.6',
    schemaLocking: false,
    directoryId: '649e2d2d2d2d2d2d2d2d2d2d',
    destinationPath: 'mammals/walrus',
    isEphemeral: false,
    pageCount: 50,
    apiRequestId: 'my-batch-request-123',
    retainOriginalZipFileName: false
  })
};

fetch('https://api.orion.file.ai/prod/v1/files/upload/multipart', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/files/upload/multipart",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'large-file.pdf',
    'fileType' => 'application/pdf',
    'fileSize' => 150.5,
    'partSizeLimit' => 10,
    'isSplit' => false,
    'isSplitExcel' => false,
    'callbackURL' => 'https://example.com/callback',
    'ocrModel' => 'Beethoven_ENG_O5.6',
    'schemaLocking' => false,
    'directoryId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'destinationPath' => 'mammals/walrus',
    'isEphemeral' => false,
    'pageCount' => 50,
    'apiRequestId' => 'my-batch-request-123',
    'retainOriginalZipFileName' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/files/upload/multipart"

	payload := strings.NewReader("{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/files/upload/multipart")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/files/upload/multipart")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"large-file.pdf\",\n  \"fileType\": \"application/pdf\",\n  \"fileSize\": 150.5,\n  \"partSizeLimit\": 10,\n  \"isSplit\": false,\n  \"isSplitExcel\": false,\n  \"callbackURL\": \"https://example.com/callback\",\n  \"ocrModel\": \"Beethoven_ENG_O5.6\",\n  \"schemaLocking\": false,\n  \"directoryId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"destinationPath\": \"mammals/walrus\",\n  \"isEphemeral\": false,\n  \"pageCount\": 50,\n  \"apiRequestId\": \"my-batch-request-123\",\n  \"retainOriginalZipFileName\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "upload_aws_xyz789",
  "key": "org_123/workspace_456/device/file_abc/document.pdf",
  "s3Path": "s3://bucket/org_123/workspace_456/device/file_abc/document.pdf",
  "partSize": 6291456,
  "totalParts": 2,
  "totalSize": 9123430,
  "presignedUrls": [
    {
      "partNumber": 1,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 0,
      "endByte": 6291455,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123429,
      "size": 2831974
    }
  ],
  "uploadId": "file_abc123xyz",
  "callbackURL": "https://example.com/callback",
  "ocrModel": "Beethoven_ENG_O5.6",
  "schemaLocking": true,
  "isSplit": false,
  "isSplitExcel": false,
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "destinationPath": "mammals/walrus",
  "isEphemeral": false
}

Initiate a multipart upload for large files (typically >100MB). This endpoint returns presigned URLs for each part that you can use to upload file chunks directly to storage.

Each presigned URL is valid for 900 seconds (15 minutes) and can be used multiple times.

How It Works

1. Initiate Upload

Call this endpoint to get presigned URLs for each part

2. Upload Parts

Upload each part to its respective presigned URL using PUT requests

3. Complete Upload

Call the complete multipart upload endpoint with all part ETags

This endpoint accepts an optional Idempotency-Key request header so a retry cannot apply the change twice. See Idempotent requests.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Optional opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true.

Body

application/json

fileName

string

required

File name

Example:

"large-file.pdf"

fileType

string

required

File type

Example:

"application/pdf"

fileSize

number

required

File size in MB

Example:

150.5

partSizeLimit

number

Part size limit in MB (optional, default will be calculated)

Example:

10

isSplit

boolean

default:false

Is split

Example:

false

isSplitExcel

boolean

Is split excel - whether to split Excel files by worksheets

Example:

false

callbackURL

string

Callback URL

Example:

"https://example.com/callback"

ocrModel

enum<string>

OCR model

Available options:

Beethoven_ENG_O5.6,

Beethoven_ENG_G5.5,

Beethoven_ENG_GP25,

Beethoven_ENG_GP25.1,

Beethoven_ENG_GP25.2,

Beethoven_CUS_O5.1,

Beethoven_CUS_O5.2,

Unified (google-document-ai-ocr-gemini-v10),

Aegis (google-document-ai-ocr-gemini-aegis-v1),

Beethoven_ZH_O5.9,

Beethoven_JP_O5.3,

Beethoven_JP_G5.4,

Beethoven_TH_O5.1,

Beethoven_TH_G5.1,

Beethoven_CUS_GP25.1,

Beethoven_Direct_Form_Filling (GP2.5)

Example:

"Beethoven_ENG_O5.6"

schemaLocking

boolean

Schema locking

Example:

false

directoryId

string

Directory Id

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

destinationPath

string

Slash-delimited folder path for the uploaded document (e.g. "mammals/walrus"). Folders are auto-created if they do not exist. Can be used together with directoryId.

Example:

"mammals/walrus"

isEphemeral

boolean

Is ephemeral

Example:

false

pageCount

number

Page count of the PDF file. Used for early validation against page limits.

Example:

50

apiRequestId

string

Optional request ID to group files uploaded in the same API session. If not provided, one is auto-generated.

Example:

"my-batch-request-123"

retainOriginalZipFileName

boolean

default:false

Retain the original file name of a ZIP upload. Only applies to zip uploads (fileType "application/zip" or a .zip file name) and is ignored for all other files. When true, the original zip name is preserved (control characters, path separators and ".." are stripped, leading/trailing dots and whitespace trimmed, capped at 255 characters) and surfaced on the extracted files as zipArchiveName. When false (default), the name is sanitized as before.

Example:

false

Response

Multipart upload initiated successfully. Use the presigned URLs to upload each part.

⌘I

fileAI API

Key Functions

Endpoints

Upload a large file using multipart upload

How It Works

Authorizations

Headers

Body

Response

​How It Works

Authorizations

Headers

Body

Response

How It Works