File Upload API

The File Upload API processes various document formats, extracts text and data, and provides specialized processing options for AI workflows. It can handle documents, images, and audio files with different extraction modes.

Base URLs

Gately AI offers two upload endpoints:

Standard Upload
Advanced Processing

POST https://api.gately.ai/v1/files

Use this endpoint for simple file uploads with basic processing options.

Supported File Types

Documents

PDF (.pdf), Word (.docx), PowerPoint (.pptx), Excel (.xlsx, .xls), Text (.txt)

Images

JPG, PNG, WEBP, GIF, SVG, BMP, TIFF

Audio

MP3, WAV, OGG, M4A (requires Azure Speech config)

Data

JSON, XML, CSV

Size Limits

Maximum file size: 50 MB per file

Processing Options

The OpenAPI playground above allows you to test file uploads with various processing options. Use the parameters described below.

Common Parameters

enable_ocr

string

default:"false"

Enable Optical Character Recognition for image-based documents

enable_vision

string

default:"true"

Enable Vision processing for images and visually-rich content

save_all

string

default:"false"

Save raw files along with processed output to storage

Advanced Parameters

text_only

string

default:"false"

Extract only text content from the document

vision_only

string

default:"false"

Process with vision models only (for images)

page_based

string

default:"false"

Return content organized by pages

images_only

string

default:"false"

Extract only images from documents

extract_mode

string

default:"default"

Extraction mode: ‘default’ or ‘embeddings’

remove_headers

string

default:"true"

Remove headers/footers from documents

Example Usage

Basic File Upload

curl -X POST \
  'https://uploud.taam.cloud/upload' \
  -F 'file=@/path/to/document.pdf'

With OCR Processing

curl -X POST \
  'https://uploud.taam.cloud/upload' \
  -F 'file=@/path/to/document.pdf' \
  -F 'enable_ocr=true' \
  -F 'enable_vision=false'

Extract for AI Embeddings

curl -X POST \
  'https://uploud.taam.cloud/upload' \
  -F 'file=@/path/to/document.pdf' \
  -F 'extract_mode=embeddings'

Page-Based Extraction

curl -X POST \
  'https://uploud.taam.cloud/upload' \
  -F 'file=@/path/to/document.pdf' \
  -F 'page_based=true'

Response Formats

Standard Processing

status

boolean

Success status of the upload and processing

content

string

Extracted text or data URL

type

string

Detected file type (pdf, docx, image, etc.)

error

string

Error message (if any)

Embeddings Mode

string

Unique identifier for the request

object

string

Object type (e.g., ‘chunks’)

created

integer

Unix timestamp when the request was created

data

object

Show Processed Data

success

boolean

Processing success status

data

object

Show Extracted Data

metadata

object

Document metadata (title, description, language)

chunks

array

Show Content Chunks

content

string

Text content of the chunk

total_tokens

integer

Number of tokens in the chunk

from_page

integer

Page number the chunk is from

usage

object

Show Usage Statistics

total_chunks

integer

Total number of chunks

total_extracted_text

integer

Total characters of extracted text

total_tokens

integer

Total number of tokens

total_pages

integer

Total number of pages

Example Response (Standard)

{
  "status": true,
  "content": "This document provides information about...",
  "type": "pdf",
  "error": ""
}

Example Response (Embeddings Mode)

{
  "id": "scrape-aec35e29-703d-4eaf-b1c4-5cda9fd66951",
  "object": "chunks",
  "created": 1732654897,
  "data": {
    "success": true,
    "data": {
      "metadata": {
        "title": "Annual_Report_2023",
        "description": "Annual financial report",
        "language": "en"
      },
      "chunks": [
        {
          "content": "Executive Summary\nThe fiscal year 2023 showed strong performance...",
          "total_tokens": 125,
          "from_page": 1
        },
        {
          "content": "Financial Highlights\nRevenue increased by 15% compared to the previous year...",
          "total_tokens": 142,
          "from_page": 2
        }
      ]
    }
  },
  "usage": {
    "total_chunks": 15,
    "total_extracted_text": 12500,
    "total_tokens": 2100,
    "total_pages": 25
  },
  "type": "pdf",
  "error": ""
}

Special Features

Document Structure Preservation

The API preserves document structure including headers, sections, lists, and tables during extraction.

PDF Processing

Advanced PDF handling including form extraction, tabular data processing, and header/footer removal.

Image Processing

Extract text from images using OCR or process them with vision models for content understanding.

Audio Transcription

Convert audio files to text transcripts (requires Azure Speech configuration).

Embeddings Preparation

Special formatting for AI embeddings generation with optimized chunking and token counting.

Error Handling

If an error occurs, the API returns a JSON object with the error message:

{
  "status": false,
  "content": "",
  "type": "error",
  "error": "File size exceeds the maximum limit"
}

Common errors include:

File size limit exceeded
Unsupported file type
OCR service unavailable
Processing timeout

Integration with AI Services

The extracted content can be used directly with Gately AI’s AI models:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document"},
        {"type": "text", "text": "EXTRACTED_DOCUMENT_CONTENT"}
      ]
    }
  ]
}

For large documents, use the embeddings mode and work with the chunked output for better AI processing.

Authorizations

Authorization

string

header

required

Enter your API key prefixed with 'Bearer '

Body

multipart/form-data

file

required

File to upload

enable_ocr

enum<string>

default:false

Enable OCR for image processing

Available options:

true,

false

enable_vision

enum<string>

default:true

Enable vision-based processing for images

Available options:

true,

false

save_all

enum<string>

default:false

Save file to configured storage

Available options:

true,

false

text_only

enum<string>

default:false

Extract only text content

Available options:

true,

false

vision_only

enum<string>

default:false

Process with vision only

Available options:

true,

false

page_based

enum<string>

default:false

Return page-based structured response

Available options:

true,

false

images_only

enum<string>

default:false

Extract only images from documents

Available options:

true,

false

extract_mode

enum<string>

default:default

Extraction mode: 'default' or 'embeddings'

Available options:

default,

embeddings

remove_headers

enum<string>

default:true

Remove headers/footers from documents

Available options:

true,

false

Response

File successfully processed

Option 1
Option 2

status

boolean

Operation status

content

string

Extracted text or data URL

type

enum<string>

Type of the processed file

Available options:

pdf,

docx,

pptx,

xlsx,

image,

audio,

text,

error

error

string

Error message (if any)

API Reference

Web & Search

File Upload

File Upload API

Base URLs

Supported File Types

Documents

Images

Audio

Data

Size Limits

Processing Options

Common Parameters

Advanced Parameters

Example Usage

Basic File Upload

With OCR Processing

Extract for AI Embeddings

Page-Based Extraction

Response Formats

Standard Processing

Embeddings Mode

Example Response (Standard)

Example Response (Embeddings Mode)

Special Features

Error Handling

Integration with AI Services

Authorizations

Body

Response

API Reference

Web & Search

​File Upload API

​Base URLs

​Supported File Types

Documents

Images

Audio

Data

​Size Limits

​Processing Options

​Common Parameters

​Advanced Parameters

​Example Usage

​Basic File Upload

​With OCR Processing

​Extract for AI Embeddings

​Page-Based Extraction

​Response Formats

​Standard Processing

​Embeddings Mode

​Example Response (Standard)

​Example Response (Embeddings Mode)

​Special Features

​Error Handling

​Integration with AI Services

Authorizations

Body

Response

File Upload API

Base URLs

Supported File Types

Size Limits

Processing Options

Common Parameters

Advanced Parameters

Example Usage

Basic File Upload

With OCR Processing

Extract for AI Embeddings

Page-Based Extraction

Response Formats

Standard Processing

Embeddings Mode

Example Response (Standard)

Example Response (Embeddings Mode)

Special Features

Error Handling

Integration with AI Services