Upload a large file using multipart upload

POST

files

upload

multipart

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",
  "blueprintId": "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",
    "blueprintId": "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',
    blueprintId: '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));

{
  "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": 6291456,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123430,
      "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",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e",
  "isEphemeral": false
}

Request · Guide: Upload files

More details

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)
blueprintId: the file type id (from GET /file-type) to use for every document in the file, skipping auto-classification. Must be an approved file type in your organization or a built-in one (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)

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, including extension.

Example:

"large-file.pdf"

fileType

string

required

The file's MIME type, such as application/pdf. This is not the fileAI file type. Accepted values: Supported file types.

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

Split a file that holds several documents into separate documents, each with its own fileId. Default false.

Example:

false

isSplitExcel

boolean

Is split excel - whether to split Excel files by worksheets

Example:

false

callbackURL

string

URL fileAI calls once (no retries) with processing updates. Requests are not signed: confirm state with the API before acting. See Processing callbacks.

Example:

"https://example.com/callback"

ocrModel

enum<string>

OCR model for this file. Omit it to use your project default; set it when a file needs a different model, for example Japanese, Chinese or Thai documents. See Read and parse.

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),

Capybara (Experimental)

Example:

"Beethoven_ENG_O5.6"

schemaLocking

boolean

Only classify into your saved schemas. See Schema locking.

Example:

false

directoryId

string

Folder to place the file in. See Files and folders.

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

blueprintId

string

File type id (the blueprintId from GET /file-type). Pre-selects that file type and its schema for every document in the file, skipping auto-classification. Must be an approved file type in your organization or a built-in one.

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

Delete the file and all related data after it is processed. Default false.

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. Each part's endByte is exclusive: PUT the bytes from startByte up to but not including endByte (size bytes).

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",
  "blueprintId": "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",
    "blueprintId": "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',
    blueprintId: '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));

{
  "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": 6291456,
      "size": 6291456
    },
    {
      "partNumber": 2,
      "presignedUrl": "https://s3.amazonaws.com/...?signature=...",
      "startByte": 6291456,
      "endByte": 9123430,
      "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",
  "blueprintId": "649e2d2d2d2d2d2d2d2d2d2e",
  "isEphemeral": false
}

Get started

Endpoints

Upload a large file using multipart upload

Authorizations

Headers

Body

Response