Skip to main content

​
Upload Files

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
  • Reference them in multiple requests
  • Reduce upload overhead
  • Manage file lifecycle
Endpoint: 
POST /v3/upload

​
Upload a File

​
Response

{
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "bytes": 152340,
  "purpose": "ocr-processing",
  "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 any Universal AI request:

​
Supported File Types

CategoryFormats
DocumentsPDF, DOC, DOCX, TXT
ImagesJPG, JPEG, PNG, GIF, BMP, TIFF, WEBP
DataCSV, JSON, XML

​
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

​
Error Handling

​
Best Practices

​
1. Reuse Files

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

# Use in multiple requests
features = [
    "ocr/financial_parser/google",
    "ocr/financial_parser/amazon",
    "ocr/identity_parser/microsoft"
]

for model in features:
    response = requests.post(
        universal_ai_url,
        headers=headers,
        json={"model": model, "input": {"file": file_id}}
    )

​
2. Track File Metadata

Keep track of uploaded files: 
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"]] = {
        "filename": result["filename"],
        "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: 
from tqdm import tqdm

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