Skip to main content
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.
PurposeUse case
assistantsAttach the file to an LLM chat completion (PDF, documents)
ocrExtract text from documents or images
financial_parserParse invoices, receipts, and financial documents
identity_parserExtract data from IDs, passports, and similar documents
resume_parserExtract structured data from CVs and resumes
speechTranscribe 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']}")

​
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/llm/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/llm/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