> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gately.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File Upload

> Upload and process files with advanced extraction capabilities

# 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:

<Card>
  <Tabs>
    <Tab title="Standard Upload">
      ```bash theme={null}
      POST https://api.gately.ai/v1/files
      ```

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

      <OpenAPIResponse path="/v1/files" method="post" />
    </Tab>

    <Tab title="Advanced Processing">
      ```bash theme={null}
      POST https://uploud.taam.cloud/upload
      ```

      Use this endpoint for advanced document processing, OCR, vision analysis, and chunking.

      <OpenAPIResponse path="/upload" method="post" />
    </Tab>
  </Tabs>
</Card>

## Supported File Types

<CardGroup cols={2}>
  <Card title="Documents" icon="file-lines">
    PDF (`.pdf`), Word (`.docx`), PowerPoint (`.pptx`), Excel (`.xlsx`, `.xls`), Text (`.txt`)
  </Card>

  <Card title="Images" icon="image">
    JPG, PNG, WEBP, GIF, SVG, BMP, TIFF
  </Card>

  <Card title="Audio" icon="microphone">
    MP3, WAV, OGG, M4A (requires Azure Speech config)
  </Card>

  <Card title="Data" icon="database">
    JSON, XML, CSV
  </Card>
</CardGroup>

## Size Limits

<Info>
  Maximum file size: **50 MB** per file
</Info>

## Processing Options

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

### Common Parameters

<ParamField query="enable_ocr" type="string" default="false">
  Enable Optical Character Recognition for image-based documents
</ParamField>

<ParamField query="enable_vision" type="string" default="true">
  Enable Vision processing for images and visually-rich content
</ParamField>

<ParamField query="save_all" type="string" default="false">
  Save raw files along with processed output to storage
</ParamField>

### Advanced Parameters

<ParamField query="text_only" type="string" default="false">
  Extract only text content from the document
</ParamField>

<ParamField query="vision_only" type="string" default="false">
  Process with vision models only (for images)
</ParamField>

<ParamField query="page_based" type="string" default="false">
  Return content organized by pages
</ParamField>

<ParamField query="images_only" type="string" default="false">
  Extract only images from documents
</ParamField>

<ParamField query="extract_mode" type="string" default="default">
  Extraction mode: 'default' or 'embeddings'
</ParamField>

<ParamField query="remove_headers" type="string" default="true">
  Remove headers/footers from documents
</ParamField>

## Example Usage

### Basic File Upload

```bash theme={null}
curl -X POST \
  'https://uploud.taam.cloud/upload' \
  -F 'file=@/path/to/document.pdf'
```

### With OCR Processing

```bash theme={null}
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

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

### Page-Based Extraction

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

## Response Formats

### Standard Processing

<ResponseField name="status" type="boolean">
  Success status of the upload and processing
</ResponseField>

<ResponseField name="content" type="string">
  Extracted text or data URL
</ResponseField>

<ResponseField name="type" type="string">
  Detected file type (pdf, docx, image, etc.)
</ResponseField>

<ResponseField name="error" type="string">
  Error message (if any)
</ResponseField>

### Embeddings Mode

<ResponseField name="id" type="string">
  Unique identifier for the request
</ResponseField>

<ResponseField name="object" type="string">
  Object type (e.g., 'chunks')
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp when the request was created
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Processed Data">
    <ResponseField name="success" type="boolean">
      Processing success status
    </ResponseField>

    <ResponseField name="data" type="object">
      <Expandable title="Extracted Data">
        <ResponseField name="metadata" type="object">
          Document metadata (title, description, language)
        </ResponseField>

        <ResponseField name="chunks" type="array">
          <Expandable title="Content Chunks">
            <ResponseField name="content" type="string">
              Text content of the chunk
            </ResponseField>

            <ResponseField name="total_tokens" type="integer">
              Number of tokens in the chunk
            </ResponseField>

            <ResponseField name="from_page" type="integer">
              Page number the chunk is from
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  <Expandable title="Usage Statistics">
    <ResponseField name="total_chunks" type="integer">
      Total number of chunks
    </ResponseField>

    <ResponseField name="total_extracted_text" type="integer">
      Total characters of extracted text
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total number of tokens
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response (Standard)

```json theme={null}
{
  "status": true,
  "content": "This document provides information about...",
  "type": "pdf",
  "error": ""
}
```

## Example Response (Embeddings Mode)

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Document Structure Preservation" icon="layer-group">
    The API preserves document structure including headers, sections, lists, and tables during extraction.
  </Accordion>

  <Accordion title="PDF Processing" icon="file-pdf">
    Advanced PDF handling including form extraction, tabular data processing, and header/footer removal.
  </Accordion>

  <Accordion title="Image Processing" icon="image">
    Extract text from images using OCR or process them with vision models for content understanding.
  </Accordion>

  <Accordion title="Audio Transcription" icon="waveform">
    Convert audio files to text transcripts (requires Azure Speech configuration).
  </Accordion>

  <Accordion title="Embeddings Preparation" icon="diagram-project">
    Special formatting for AI embeddings generation with optimized chunking and token counting.
  </Accordion>
</AccordionGroup>

## Error Handling

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

```json theme={null}
{
  "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:

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

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


## OpenAPI

````yaml POST /upload
openapi: 3.0.1
info:
  title: TaamCloud API
  description: >-
    A collection of AI services including chat, embeddings, reranking, and media
    generation
  version: 1.0.0
servers:
  - url: https://api.gately.ai
    description: Main API server
  - url: https://uploud.taam.cloud
    description: File Processing server
security:
  - bearerAuth: []
paths:
  /upload:
    post:
      tags:
        - Files
      summary: Upload and process files
      description: >-
        Process various file types including documents, images, and audio files
        with advanced extraction options
      operationId: upload
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
      responses:
        '200':
          description: File successfully processed
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/FileUploadResponse'
                  - $ref: '#/components/schemas/FileEmbeddingsResponse'
        '400':
          description: Invalid file format or request
        '413':
          description: File size exceeds limit
        '500':
          description: Processing error
components:
  schemas:
    FileUploadRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: File to upload
        enable_ocr:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Enable OCR for image processing
        enable_vision:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'true'
          description: Enable vision-based processing for images
        save_all:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Save file to configured storage
        text_only:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Extract only text content
        vision_only:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Process with vision only
        page_based:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Return page-based structured response
        images_only:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'false'
          description: Extract only images from documents
        extract_mode:
          type: string
          enum:
            - default
            - embeddings
          default: default
          description: 'Extraction mode: ''default'' or ''embeddings'''
        remove_headers:
          type: string
          enum:
            - 'true'
            - 'false'
          default: 'true'
          description: Remove headers/footers from documents
    FileUploadResponse:
      type: object
      properties:
        status:
          type: boolean
          description: Operation status
        content:
          type: string
          description: Extracted text or data URL
        type:
          type: string
          enum:
            - pdf
            - docx
            - pptx
            - xlsx
            - image
            - audio
            - text
            - error
          description: Type of the processed file
        error:
          type: string
          description: Error message (if any)
    FileEmbeddingsResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the request
        object:
          type: string
          description: Object type (e.g., 'chunks')
        created:
          type: integer
          description: Unix timestamp when the request was created
        data:
          type: object
          properties:
            success:
              type: boolean
            data:
              type: object
              properties:
                metadata:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Document title
                    description:
                      type: string
                      description: Document description
                    language:
                      type: string
                      description: Document language
                chunks:
                  type: array
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: Text content of the chunk
                      total_tokens:
                        type: integer
                        description: Number of tokens in the chunk
                      from_page:
                        type: integer
                        description: Page number the chunk is from
        usage:
          type: object
          properties:
            total_chunks:
              type: integer
              description: Total number of chunks
            total_extracted_text:
              type: integer
              description: Total characters of extracted text
            total_tokens:
              type: integer
              description: Total number of tokens
            total_pages:
              type: integer
              description: Total number of pages
        type:
          type: string
          description: Type of the processed file
        error:
          type: string
          description: Error message (if any)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Enter your API key prefixed with 'Bearer '

````