File upload

Learn how to upload and manage files with V3’s persistent file storage system.

Overview

V3 introduces persistent file storage that allows you to:

Upload files once and reference them across multiple requests
Reduce upload overhead and latency
Manage file lifecycle with automatic expiration

Endpoint:

POST /v3/upload

File Intent (purpose)

The purpose field is optional. When provided, it tags the file with its intended use making it easy to filter your uploaded files by intent when retrieving them later.

Purpose	Use case
`assistants`	Attach the file to an LLM chat completion (PDF, documents)
`ocr`	Extract text from documents or images
`financial_parser`	Parse invoices, receipts, and financial documents
`identity_parser`	Extract data from IDs, passports, and similar documents
`resume_parser`	Extract structured data from CVs and resumes
`speech`	Transcribe audio files

Upload a File

import requests

url = "https://api.edenai.run/v3/upload"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# Upload file
files = {
    "file": open("document.pdf", "rb")
}

data = {
    "purpose": "assistants"  # Optional: describe intended use
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(f"File ID: {result['file_id']}")
print(f"Filename: {result['file_name']}")
print(f"Size: {result['file_size']} bytes")
print(f"Expires at: {result['expires_at']}")

curl -X POST https://api.edenai.run/v3/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "purpose=assistants"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('purpose', 'assistants');

const response = await fetch('https://api.edenai.run/v3/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log('File ID:', result.file_id);

Response

{
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_name": "document.pdf",
  "file_size": 152340,
  "file_mimetype": "application/pdf",
  "purpose": "ocr-processing",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-22T10:30:00Z"
}

Use Uploaded File

Once uploaded, reference the file by its file_id in an LLM chat completion:

import requests

url = "https://api.edenai.run/v3/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "openai/gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this document."},
                {"type": "file", "file": {"file_id": "550e8400-e29b-41d4-a716-446655440000"}}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result["choices"][0]["message"]["content"])

File Size Limits

Default maximum: 100 MB per file
Actual limits may vary by feature and provider
Check provider-specific documentation for exact limits

File Expiration

Files are automatically deleted after a retention period:

Default retention: 7 days
Files expire at the timestamp shown in expires_at
Expired files cannot be recovered
Upload new files as needed

Upload Multiple Files

import requests

url = "https://api.edenai.run/v3/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

files_to_upload = [
    "invoice1.pdf",
    "invoice2.pdf",
    "invoice3.pdf"
]

file_ids = []

for filepath in files_to_upload:
    files = {"file": open(filepath, "rb")}
    data = {"purpose": "assistants"}
        
    response = requests.post(url, headers=headers, files=files, data=data)
    result = response.json()
        
    file_ids.append({
        "filename": filepath,
        "file_id": result["file_id"]
    })
        
    print(f"Uploaded {filepath}: {result['file_id']}")

# Use file IDs in subsequent requests
for item in file_ids:
    print(f"{item['filename']}: {item['file_id']}")

Error Handling

import requests
from requests.exceptions import RequestException

def safe_upload(filepath):
    """Upload file with error handling"""
        
    url = "https://api.edenai.run/v3/upload"
    headers = {"Authorization": "Bearer YOUR_API_KEY"}
        
    try:
        with open(filepath, "rb") as f:
            files = {"file": f}
            response = requests.post(url, headers=headers, files=files)
            response.raise_for_status()
                
            result = response.json()
            return {
                "success": True,
                "file_id": result["file_id"],
                "file_name": result["file_name"]
            }
                
    except FileNotFoundError:
        return {"success": False, "error": "File not found"}
    except RequestException as e:
        return {"success": False, "error": str(e)}
    except Exception as e:
        return {"success": False, "error": f"Unexpected error: {str(e)}"}

# Usage
result = safe_upload("document.pdf")
if result["success"]:
    print(f"Uploaded: {result['file_id']}")
else:
    print(f"Error: {result['error']}")

Best Practices

1. Reuse Files

Upload once, use in multiple requests:

import requests

upload_url = "https://api.edenai.run/v3/upload"
llm_url = "https://api.edenai.run/v3/chat/completions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("document.pdf", "rb")}

# Upload file once
upload_response = requests.post(upload_url, headers=headers, files=files)
file_id = upload_response.json()["file_id"]

# Query with multiple models without re-uploading
models = [
    "openai/gpt-4o",
    "anthropic/claude-sonnet-4-5",
    "google/gemini-2.5-flash"
]

for model in models:
    response = requests.post(
        llm_url,
        headers=headers,
        json={
            "model": model,
            "messages": [
                {
                    "role": "user",
                    "content": [
                        {"type": "text", "text": "Summarize this document."},
                        {"type": "file", "file": {"file_id": file_id}}
                    ]
                }
            ]
        }
    )

2. Track File Metadata

Keep track of uploaded files:

import requests

upload_url = "https://api.edenai.run/v3/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

uploaded_files = {}

def upload_and_track(filepath, purpose=None):
    files = {"file": open(filepath, "rb")}
    data = {"purpose": purpose} if purpose else {}

    response = requests.post(upload_url, headers=headers, files=files, data=data)
    result = response.json()
    
    # Store metadata
    uploaded_files[result["file_id"]] = {
        "file_name": result["file_name"],
        "uploaded_at": result["created_at"],
        "expires_at": result["expires_at"],
        "purpose": purpose
    }
    
    return result["file_id"]

3. Handle Large Files

For large files, show upload progress:

import os
import requests
from tqdm import tqdm

upload_url = "https://api.edenai.run/v3/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

def upload_with_progress(filepath):
    """Upload file with progress bar"""

    file_size = os.path.getsize(filepath)

    with open(filepath, 'rb') as f:
        with tqdm(total=file_size, unit='B', unit_scale=True) as pbar:
            files = {'file': f}
            response = requests.post(
                upload_url,
                headers=headers,
                files=files
            )
            pbar.update(file_size)

    return response.json()

Common Errors

413 Payload Too Large

File exceeds size limit. Compress or split the file.

415 Unsupported Media Type

File format not supported. Check supported formats above.

422 Validation Error

Invalid request format. Ensure file field is properly set.

Next Steps

Chat Completions

Use uploaded files in LLM conversations

Streaming

Stream responses when processing documents

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Overview

File Intent (purpose)

Upload a File

Response

Use Uploaded File

File Size Limits

File Expiration

Upload Multiple Files

Error Handling

Best Practices

1. Reuse Files

2. Track File Metadata

3. Handle Large Files

Common Errors

413 Payload Too Large

415 Unsupported Media Type

422 Validation Error

Next Steps

Chat Completions

Streaming

​Overview

​File Intent (purpose)

​Upload a File

​Response

​Use Uploaded File

​File Size Limits

​File Expiration

​Upload Multiple Files

​Error Handling

​Best Practices

​1. Reuse Files

​2. Track File Metadata

​3. Handle Large Files

​Common Errors

​413 Payload Too Large

​415 Unsupported Media Type

​422 Validation Error

​Next Steps

Chat Completions

Streaming

Overview

File Intent (purpose)

Upload a File

Response

Use Uploaded File

File Size Limits

File Expiration

Upload Multiple Files

Error Handling

Best Practices

1. Reuse Files

2. Track File Metadata

3. Handle Large Files

Common Errors

413 Payload Too Large

415 Unsupported Media Type

422 Validation Error

Next Steps