API Documentation

Quick Start

npm install axios form-data

const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const API_KEY = 'ffc_live_your_api_key';
const API_URL = 'https://freefastconverter.com/api/external/v1';

async function convertImage(filePath, outputFormat) {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('output_format', outputFormat);
  form.append('quality', 'balanced');

  try {
    const response = await axios.post(`${API_URL}/convert/image`, form, {
      headers: {
        'X-API-Key': API_KEY,
        ...form.getHeaders()
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Conversion failed:', error.response?.data);
    throw error;
  }
}

// Usage
const result = await convertImage('./image.png', 'webp');
console.log('Job:', result.job_id, result.status_url);

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header.

X-API-Key: ffc_live_your_api_key_here

API Endpoints

Convert an uploaded file using an API key. Use image, document, video, or audio as the media type.

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "input_format": "png",
  "output_format": "webp",
  "status_url": "/api/external/v1/jobs/job_abc123xyz",
  "result_url": "/api/external/v1/jobs/job_abc123xyz/result",
  "estimated_wait_seconds": 5
}

Use Cases

Why use the API

The API runs the same conversion engine as the website — so a file you convert via the API is produced by the exact same pipeline, with identical output. It just adds programmatic access so you can build it into your own product or automate at scale.

Use it from AI assistants (MCP)

Connect the converter to Claude Desktop, Claude Code, Cursor, or any MCP-compatible assistant. Then just ask — "convert this HEIC to PNG" or "compress this PDF" — and it runs the conversion through your API key. Powered by the open Model Context Protocol.

Requirements: Node.js 18+ and an API key. No install needed — npx fetches the server automatically.

Add it to your assistant

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "freefast-converter": {
      "command": "npx",
      "args": ["-y", "freefast-converter-mcp"],
      "env": { "FFC_API_KEY": "ffc_live_your_key_here" }
    }
  }
}

Claude Code: claude mcp add freefast-converter -e FFC_API_KEY=ffc_live_... -- npx -y freefast-converter-mcp

Tools the assistant gets

The MCP server simply wraps the same REST endpoints documented on this page, so anything the API can do, your AI assistant can do too.

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with error details.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "retry_after": 60
  }
}

Webhooks

Receive real-time notifications when jobs complete. Configure webhook URLs in your dashboard or per-request.

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "download_url": "https://cdn.freefastconverter.com/...",
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=abc123..."
}

Rate Limits