Skip to main content
Upload files to the system for processing. Supports both URL downloads and direct file uploads.

​
Upload File

POST /v1/files/upload
Files are automatically organized by type:
CategoryStorage PathExtensions
Imagesassets/image/.jpg, .jpeg, .png, .gif, .webp, .bmp, .svg
Videosassets/video/.mp4, .avi, .mov, .wmv, .flv, .webm, .mkv
Audioassets/audio/.mp3, .wav, .flac, .aac, .ogg, .m4a
Documentsassets/docs/.pdf, .doc, .docx, .txt, .ppt, .pptx, .xls, .xlsx, .csv

​
Method 1: URL Upload

Download a file from a URL. 
{
  "file_url": "https://example.com/document.pdf",
  "file_type": "auto"
}
ParameterTypeDescription
file_urlstringURL of the file to download
file_typestringType of file (pdf, image, audio, video, auto)
import requests

response = requests.post(
    "https://api.bithuman.ai/v1/files/upload",
    headers={
        "Content-Type": "application/json",
        "api-secret": "YOUR_API_SECRET"
    },
    json={
        "file_url": "https://example.com/presentation.pdf",
        "file_type": "auto"
    }
)
print(response.json())

​
Method 2: Direct Upload

Upload base64-encoded file data directly. 
{
  "file_data": "JVBERi0xLjQKJcOkw7zDtsO...",
  "file_name": "document.pdf",
  "file_type": "auto"
}
ParameterTypeDescription
file_datastringBase64 encoded file data
file_namestringOriginal filename
file_typestringType of file (pdf, image, audio, video, auto)
import requests
import base64

with open("document.pdf", "rb") as f:
    file_data = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    "https://api.bithuman.ai/v1/files/upload",
    headers={
        "Content-Type": "application/json",
        "api-secret": "YOUR_API_SECRET"
    },
    json={
        "file_data": file_data,
        "file_name": "document.pdf",
        "file_type": "auto"
    }
)
print(response.json())

​
Response (both methods)

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "file_url": "https://storage.supabase.co/assets/docs/20250115_103000_abc12345.pdf",
    "original_source": "https://example.com/document.pdf",
    "file_type": "auto",
    "file_size": 1024000,
    "mime_type": "application/pdf",
    "asset_category": "docs",
    "uploaded_at": "2025-01-15T10:30:00Z"
  }
}

​
Size Limits

CategoryMax Size
Images10 MB
Videos100 MB
Audio50 MB
Documents10 MB
Exceeding these limits returns HTTP 413.

​
Upload Methods Comparison

MethodBest ForProsCons
URL UploadExternal files, cloud storageNo file size limits, efficientRequires accessible URL
Direct UploadLocal files, form uploadsWorks with any file sourceLimited by request size

​
Complete Examples

​
Batch Upload

import requests
import base64
from pathlib import Path

def batch_upload_files(directory_path):
    results = []
    for file_path in Path(directory_path).iterdir():
        if file_path.is_file():
            with open(file_path, "rb") as f:
                file_data = base64.b64encode(f.read()).decode('utf-8')

            response = requests.post(
                "https://api.bithuman.ai/v1/files/upload",
                headers={
                    "Content-Type": "application/json",
                    "api-secret": "YOUR_API_SECRET"
                },
                json={
                    "file_data": file_data,
                    "file_name": file_path.name,
                    "file_type": "auto"
                }
            )
            results.append({
                "filename": file_path.name,
                "status": "success" if response.status_code == 200 else "error"
            })
    return results

results = batch_upload_files("./documents")
for r in results:
    print(f"{r['filename']}: {r['status']}")

​
Error Codes

HTTP StatusMeaning
200Success
400Bad request (invalid parameters)
401Unauthorized (invalid API secret)
413File too large
415Unsupported file type
500Internal server error