Developer API Reference

FileFran is a targeted, high-performance media delivery and asset processing cloud hosted at filefran.safespaceshub.com. It is engineered for Images, PDFs, Documents, Audio, and Video with real-time dynamic transformations, automated Opus/H.264 compression, and temporal AI chunking.

Authentication

FileFran authenticates API requests via a secret Bearer token or custom header. Obtain your API key from the dashboard or through admin issuance.

# Standard Authorization header
Authorization: Bearer ffran_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Or via custom header
X-API-KEY: ffran_live_xxxxxxxxxxxxxxxxxxxxxxxx

Strict 5MB Limit & Image Compressor

Every uploaded image goes through a strict multi-pass compressor that:

1. Bounds maximum dimensions to 1920px (preserving aspect ratio).
2. Transcodes into highly optimized WebP format.
3. Reduces file footprint down to kilobytes (typically 50 KB – 300 KB), saving bandwidth and storage.

POST /api/v1/files/upload

Upload a file using multipart/form-data.

Request Headers

Authorization: Bearer ffran_live_...
Content-Type: multipart/form-data

Form Fields

cURL Example

curl -X POST https://filefran.safespaceshub.com/api/v1/files/upload \
  -H "Authorization: Bearer ffran_live_..." \
  -F "file=@photo.jpg"

Success Response (201 Created)

{
  "success": true,
  "file": {
    "id": "file_893bf9d23ab1",
    "filename": "photo.jpg",
    "category": "image",
    "mimeType": "image/webp",
    "sizeBytes": 142850,
    "sizeFormatted": "139.5 KB",
    "width": 1280,
    "height": 720,
    "compression": {
      "originalSizeBytes": 3200000,
      "compressedSizeBytes": 142850,
      "compressedSizeFormatted": "139.5 KB",
      "reductionPercent": "95.5%"
    },
    "url": "https://filefran.safespaceshub.com/view/file_893bf9d23ab1",
    "downloadUrl": "https://filefran.safespaceshub.com/api/v1/files/file_893bf9d23ab1/download"
  },
  "quota": {
    "creditsRemaining": 0.9998,
    "bytesRemaining": 1073598974,
    "usagePercent": 0.01
  }
}

On-the-Fly Dynamic Transformations

Transform, resize, crop, convert format, and apply effects dynamically in real-time directly via the URL path:

https://filefran.safespaceshub.com/view/:fileId/:transformation

Examples

# 1. Resize to 600x400 with cover crop:
https://filefran.safespaceshub.com/view/file_123/w_600,h_400,c_fill

# 2. Convert to WebP at 80% quality:
https://filefran.safespaceshub.com/view/file_123/f_webp,q_80

# 3. Grayscale with blur:
https://filefran.safespaceshub.com/view/file_123/w_500,blur_4,e_grayscale

# 4. Extract Page 1 from a multi-page PDF:
https://filefran.safespaceshub.com/view/file_pdf_456/p_1

Supported Transformation Parameters

AI Feature Extraction

Every stored image and document is automatically analyzed and indexed for downstream AI vision models, OCR engines, or RAG pipelines.

GET https://filefran.safespaceshub.com/api/v1/ai/extract/:id
Authorization: Bearer ffran_live_...

Returns dominant hex colors, perceptual brightness, channel statistics, aspect orientation, perceptual vectors, and prompt context strings.

AI Dataset Export (JSON / JSONL)

Export all workspace files formatted as multimodal AI training/evaluation manifests with direct CDN links and context prompts:

# JSON format:
GET https://filefran.safespaceshub.com/api/v1/ai/manifest

# JSONL format (ideal for fine-tuning or bulk ingestion):
GET https://filefran.safespaceshub.com/api/v1/ai/manifest?format=jsonl

Audio & Video Temporal Chunks & AI Streaming

Audio and video files are compressed into ultra-low-footprint Opus / H.264 formats and partitioned into timestamped temporal slices (15s for audio, 6s for video) for rapid speech recognition and vision-language model indexing:

GET https://filefran.safespaceshub.com/api/v1/ai/media-manifest/:id
Authorization: Bearer ffran_live_...

Returns timestamped chunk IDs, duration slices, size in KBs, and individual direct streaming links (/view/:fileId/chunk_:index) allowing AI models to process seconds of media rather than downloading multi-megabyte streams.

Model Context Protocol (MCP) Server

FileFran provides an official, hardened Model Context Protocol (MCP) server allowing AI agents in Claude Desktop, Cursor, Windsurf, or Antigravity to directly upload files, extract visual/textual features, query audio/video temporal chunks, and generate transformed dynamic URLs within agent workflows.

1. Available MCP Tools

2. Claude Desktop Integration

Add the following configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "filefran": {
      "command": "node",
      "args": ["/absolute/path/to/imageinfra/mcp/index.js"],
      "env": {
        "FILEFRAN_API_KEY": "ffran_live_YOUR_API_KEY",
        "FILEFRAN_URL": "https://filefran.safespaceshub.com"
      }
    }
  }
}

3. Cursor & Windsurf Integration

In Cursor Settings → Features → MCP Servers, click + Add New MCP Server:

• Name: filefran
• Type: command
• Command: node /absolute/path/to/imageinfra/mcp/index.js

Ensure the environment variables FILEFRAN_API_KEY and FILEFRAN_URL are configured or declared in your project's .env file.

4. Direct Agent Prompt Example

Once registered, you can prompt your LLM agent naturally:

"Upload the screenshot at ./assets/diagram.png to FileFran, extract its dominant colors and perceptual vector, and give me a 400px wide WebP thumbnail URL for our README."

The agent will autonomously execute filefran_upload_media, followed by filefran_get_ai_features and filefran_transform_url, returning the exact optimized URLs and structured embeddings.

Google Photos & Google Drive Migration

Seamlessly migrate an entire Google Photos or Google Drive export. All files are automatically filtered to supported media (images, PDFs, documents, audio, and video), compressed to lightweight footprints, and stored securely.

# Batch Google Takeout ZIP upload:
curl -X POST https://filefran.safespaceshub.com/api/v1/integrations/google/takeout-zip \
  -H "Authorization: Bearer ffran_live_..." \
  -F "archive=@GooglePhotosExport.zip"

Whop.com Automated Billing & 1GB Quota

Subscriptions and renewals are processed at https://whop.com/safespaceshub/imageinfra.

When users pay, Whop triggers our automated webhook, updating their renewal date and immediately granting 50 GB capped consumption allowance without manual intervention.

POST https://filefran.safespaceshub.com/api/v1/webhooks/whop

Real-World Use Case 1: Image Upload, WebP Compression & Vision AI Extraction

Goal: Upload a raw 3MB smartphone photo, compress it into ~80 KB WebP, extract the dominant color hex and 8x8 perceptual vector, and inject the metadata directly into a vision model prompt.

Node.js / TypeScript Example

import fs from 'fs';

async function uploadAndAnalyzeImage() {
  const fileStream = fs.createReadStream('./sunset.jpg');
  const formData = new FormData();
  formData.append('file', new Blob([fs.readFileSync('./sunset.jpg')]), 'sunset.jpg');

  const res = await fetch('https://filefran.safespaceshub.com/api/v1/files/upload', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer ffran_live_YOUR_KEY' },
    body: formData
  });

  const data = await res.json();
  console.log('Stored Compressed WebP URL:', data.file.url);
  console.log('Compression Ratio:', data.file.compression.reductionPercent); // e.g. "97.4%"
  console.log('Dominant Color:', data.file.aiFeatures.colorProfile.dominantHex); // e.g. "#ff6432"
  console.log('Perceptual 8x8 Vector:', data.file.aiFeatures.aiVector8x8); // 64-element matrix

  // Inject into LLM context prompt:
  const prompt = `Context: ${data.file.aiFeatures.aiPromptContext}. Image URL: ${data.file.url}`;
  return prompt;
}

Real-World Use Case 2: Voice Audio Ingestion & 15s Slicing for Whisper / ASR

Goal: Ingest meeting recordings, interviews, or voice notes (WAV/MP3). Transcode to 32kbps Opus (~240KB/min) and retrieve individual 15-second chunks for parallel transcription.

Python / Requests Example

import requests

API_KEY = "ffran_live_YOUR_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Upload audio recording
with open("meeting.wav", "rb") as f:
    upload_res = requests.post(
        "https://filefran.safespaceshub.com/api/v1/files/upload",
        headers=headers,
        files={"file": ("meeting.wav", f, "audio/wav")}
    ).json()

file_id = upload_res["file"]["id"]
print(f"Compressed audio to Opus: {upload_res['file']['sizeFormatted']}")

# 2. Retrieve AI Media Manifest with 15-second slices
manifest = requests.get(
    f"https://filefran.safespaceshub.com/api/v1/ai/media-manifest/{file_id}",
    headers=headers
).json()

for chunk in manifest["chunks"]:
    print(f"Chunk {chunk['index']} ({chunk['timeframe']['label']}): {chunk['streamUrl']}")
    # Feed chunk['streamUrl'] directly to OpenAI Whisper, Gemini Audio, or local speech-to-text models

Real-World Use Case 3: Video Scene Search & Keyframe Vision Indexing

Goal: Store video lectures, agricultural/environmental field videos, or product demos. Compress to 720p H.264 CRF 28, extract keyframes every 3 seconds, and slice into 6-second streaming chunks.

cURL & AI Query Workflow

# 1. Upload video (up to 25MB before compression):
curl -X POST https://filefran.safespaceshub.com/api/v1/files/upload \
  -H "Authorization: Bearer ffran_live_YOUR_KEY" \
  -F "file=@demo.mp4"

# 2. Get temporal chunk manifest:
curl -s https://filefran.safespaceshub.com/api/v1/ai/media-manifest/file_abc123 \
  -H "Authorization: Bearer ffran_live_YOUR_KEY"

# Response provides lightweight 6-second streaming slices:
# https://filefran.safespaceshub.com/view/file_abc123/chunk_0  (0.0s - 6.0s)
# https://filefran.safespaceshub.com/view/file_abc123/chunk_1  (6.0s - 12.0s)
# Web clients and AI models stream only the relevant 6s slice instead of full multi-megabyte videos.

Real-World Use Case 4: Google Photos & Drive Full Library Migration

Goal: Move an entire Google Photos Takeout export or Google Drive folder archive into FileFran with automated filtering, strict <5MB compliance, and multi-pass compression into kilobytes.

Batch Takeout cURL Example

# Stream full Takeout ZIP archive:
curl -X POST https://filefran.safespaceshub.com/api/v1/integrations/google/takeout-zip \
  -H "Authorization: Bearer ffran_live_YOUR_KEY" \
  -F "archive=@takeout-20261028-photos.zip"

# Response:
{
  "success": true,
  "summary": {
    "totalProcessed": 48,
    "importedCount": 42,
    "skippedCount": 6
  },
  "results": {
    "imported": [
      {
        "filename": "IMG_2026_01.jpg",
        "category": "image",
        "originalSize": 3845920,
        "finalCompressedSize": 142100,
        "sizeFormatted": "138.8 KB",
        "reduction": "96.3%",
        "publicUrl": "https://filefran.safespaceshub.com/view/file_89ab32"
      }
    ]
  }
}