File Conversion API Guide: Integrate Format Conversion into Your App

File Conversion API Guide: Integrate Format Conversion into Your App — Blog | ConvertIntoMP4

Core API Patterns

File conversion APIs typically follow one of two patterns depending on whether the conversion is fast enough to complete synchronously or requires asynchronous processing.

Synchronous Conversion

For small files and fast conversions (image format changes, simple document conversions), a synchronous API returns the converted file directly in the response:

POST /api/convert
Content-Type: multipart/form-data

file: [binary data]
outputFormat: png
quality: 85

Response: 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="output.png"
[binary data]

Advantages: Simple to implement, no polling or callbacks needed, works well with serverless functions.

Limitations: HTTP timeouts (typically 30-60 seconds) limit file size and conversion complexity. Not suitable for video transcoding, large batch operations, or any conversion that takes more than a few seconds.

Asynchronous Conversion (Job-Based)

For larger files and complex conversions, the API creates a job and returns immediately. The client polls for completion or receives a webhook callback:

POST /api/jobs
Content-Type: application/json

{
  "input": "https://storage.example.com/input.mov",
  "outputFormat": "mp4",
  "options": {
    "codec": "h264",
    "quality": "high",
    "resolution": "1080p"
  },
  "webhook": "https://your-app.com/webhooks/conversion"
}

Response: 202 Accepted
{
  "jobId": "job_abc123",
  "status": "queued",
  "estimatedDuration": 45,
  "createdAt": "2026-02-19T10:30:00Z"
}

This is the standard pattern for video conversion, audio processing, and any operation that takes more than a few seconds.

Pattern Comparison

Aspect	Synchronous	Asynchronous
Latency	Low (seconds)	Higher (seconds to minutes)
File size limit	Small (10-50 MB typical)	Large (GB+)
Complexity	Simple	More complex (polling/webhooks)
Timeout risk	High for large files	None
Progress tracking	Not possible	Yes (percentage, ETA)
Batch support	Sequential only	Parallel processing
Best for	Images, small documents	Video, audio, large batches

Authentication and Security

API Key Authentication

Most conversion APIs use API keys for authentication. Keys are passed in a request header:

curl -X POST https://api.example.com/convert \
  -H "Authorization: Bearer sk_live_abc123xyz" \
  -F "file=@input.pdf" \
  -F "outputFormat=docx"

Best practices for API keys:

Store keys in environment variables, never in source code
Use separate keys for development and production
Rotate keys periodically (every 90 days is a common policy)
Scope keys to specific permissions (read-only, convert-only, admin)
Monitor key usage for anomalies

Signed URLs for File Access

Instead of uploading files directly to the conversion API, you can provide signed URLs that give the API temporary access to files in your cloud storage:

{
  "input": {
    "url": "https://s3.amazonaws.com/bucket/file.pdf?X-Amz-Signature=...",
    "expiresIn": 3600
  },
  "output": {
    "url": "https://s3.amazonaws.com/bucket/converted/?X-Amz-Signature=...",
    "expiresIn": 3600
  },
  "outputFormat": "docx"
}

This approach keeps large files off the API server's network, reduces latency, and improves security since the API never stores your files.

Pro Tip: Always use signed URLs with short expiration times (1 hour or less) for input and output files. This minimizes the window of unauthorized access if a URL is leaked. For sensitive documents, our guide on data privacy in file conversion covers additional security measures.

Webhook Callbacks

Webhooks eliminate the need for polling by pushing status updates to your application as they happen. When a conversion job changes status, the API sends an HTTP POST to your registered webhook URL.

Webhook Payload

{
  "event": "job.completed",
  "jobId": "job_abc123",
  "status": "completed",
  "input": {
    "filename": "presentation.pptx",
    "format": "pptx",
    "size": 4521984
  },
  "output": {
    "url": "https://cdn.example.com/results/job_abc123/output.pdf",
    "format": "pdf",
    "size": 2145792,
    "expiresAt": "2026-02-20T10:30:00Z"
  },
  "duration": 3.2,
  "timestamp": "2026-02-19T10:30:03Z"
}

Webhook Event Types

Event	Description	Action
`job.queued`	Job accepted and waiting for processing	Update UI to show "Queued"
`job.processing`	Conversion has started	Update UI to show "Converting"
`job.progress`	Progress update (percentage)	Update progress bar
`job.completed`	Conversion finished successfully	Download output, notify user
`job.failed`	Conversion failed	Show error, retry or notify user
`job.cancelled`	Job was cancelled by the client	Clean up resources

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests come from the legitimate API and not an attacker:

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(payload, "utf8").digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// In your webhook handler
app.post("/webhooks/conversion", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = verifyWebhook(JSON.stringify(req.body), signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Process the webhook event
  const { event, jobId, output } = req.body;

  switch (event) {
    case "job.completed":
      // Download the converted file or update your database
      handleCompletion(jobId, output);
      break;
    case "job.failed":
      handleFailure(jobId, req.body.error);
      break;
  }

  res.status(200).json({ received: true });
});

Pro Tip: Implement idempotent webhook handlers. Webhooks may be delivered more than once (due to retries). Use the jobId to check if you have already processed the event before taking action.

Batch Processing

Converting many files at once is a common requirement. The API approach to batch processing varies by provider.

Batch Job Submission

POST /api/batch
{
  "jobs": [
    {
      "input": "https://storage.example.com/doc1.docx",
      "outputFormat": "pdf"
    },
    {
      "input": "https://storage.example.com/doc2.docx",
      "outputFormat": "pdf"
    },
    {
      "input": "https://storage.example.com/image1.png",
      "outputFormat": "webp",
      "options": { "quality": 80 }
    }
  ],
  "webhook": "https://your-app.com/webhooks/batch",
  "callbackMode": "batch"
}

Response: 202 Accepted
{
  "batchId": "batch_xyz789",
  "jobCount": 3,
  "status": "processing",
  "jobs": [
    { "jobId": "job_001", "status": "queued" },
    { "jobId": "job_002", "status": "queued" },
    { "jobId": "job_003", "status": "queued" }
  ]
}

Batch processing dashboard showing multiple conversion jobs with progress indicators

Callback Modes

Per-job callbacks: Receive a webhook for each individual job as it completes. Best when you want to process results incrementally.
Batch callbacks: Receive a single webhook when all jobs in the batch complete. Best when you need all results before proceeding.
Both: Receive per-job updates for progress tracking and a final batch callback for the aggregate result.

For a deep dive into batch conversion strategies, including parallel processing, error recovery, and progress tracking, see our batch processing files guide.

Rate Limiting and Quotas

Conversion APIs enforce rate limits to ensure fair resource allocation and prevent abuse. Understanding these limits is essential for building reliable integrations.

Common Rate Limit Structures

Tier	Requests/Min	Concurrent Jobs	Max File Size	Monthly Quota
Free	10	2	25 MB	100 conversions
Starter	60	5	100 MB	1,000 conversions
Professional	300	20	500 MB	10,000 conversions
Enterprise	Custom	Custom	Custom	Unlimited

Handling Rate Limits

APIs communicate rate limit status through HTTP headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708340400
Retry-After: 45

Implement exponential backoff with jitter to handle rate limits gracefully:

import time
import random
import requests

def convert_with_retry(file_url, output_format, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.example.com/convert",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={
                "input": file_url,
                "outputFormat": output_format
            }
        )

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            # Exponential backoff with jitter
            retry_after = int(response.headers.get("Retry-After", 0))
            backoff = max(retry_after, (2 ** attempt) + random.uniform(0, 1))
            print(f"Rate limited. Retrying in {backoff:.1f}s...")
            time.sleep(backoff)
            continue

        if response.status_code >= 500:
            # Server error, retry with backoff
            time.sleep((2 ** attempt) + random.uniform(0, 1))
            continue

        # Client error, do not retry
        response.raise_for_status()

    raise Exception("Max retries exceeded")

Error Handling

Robust error handling is critical for a production integration. Conversion APIs can fail for many reasons, and your application needs to handle each gracefully.

Error Response Format

{
  "error": {
    "code": "UNSUPPORTED_FORMAT",
    "message": "The input format 'xyz' is not supported for conversion to 'pdf'",
    "details": {
      "inputFormat": "xyz",
      "outputFormat": "pdf",
      "supportedInputFormats": ["docx", "xlsx", "pptx", "txt", "html", "md"]
    },
    "requestId": "req_abc123"
  }
}

Common Error Codes

HTTP Status	Error Code	Description	Recovery
400	`INVALID_REQUEST`	Malformed request body	Fix request parameters
400	`UNSUPPORTED_FORMAT`	Format pair not supported	Check supported formats
401	`UNAUTHORIZED`	Invalid or missing API key	Check API key
403	`QUOTA_EXCEEDED`	Monthly quota reached	Upgrade plan or wait for reset
404	`JOB_NOT_FOUND`	Job ID does not exist	Check job ID
413	`FILE_TOO_LARGE`	File exceeds size limit	Compress or split file
422	`CORRUPT_FILE`	Input file is damaged	Re-upload or use a different file
429	`RATE_LIMITED`	Too many requests	Retry with backoff
500	`INTERNAL_ERROR`	Server-side failure	Retry after delay
503	`SERVICE_UNAVAILABLE`	Temporary overload	Retry with backoff

Building a Resilient Client

class ConversionClient {
  private apiKey: string;
  private baseUrl: string;
  private maxRetries: number;

  constructor(apiKey: string, baseUrl: string, maxRetries = 3) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
    this.maxRetries = maxRetries;
  }

  async convert(inputUrl: string, outputFormat: string, options = {}) {
    const response = await this.request("/api/jobs", {
      method: "POST",
      body: JSON.stringify({
        input: inputUrl,
        outputFormat,
        options,
      }),
    });

    return response;
  }

  async getJob(jobId: string) {
    return this.request(`/api/jobs/${jobId}`);
  }

  async waitForCompletion(jobId: string, timeout = 300000) {
    const start = Date.now();

    while (Date.now() - start < timeout) {
      const job = await this.getJob(jobId);

      if (job.status === "completed") return job;
      if (job.status === "failed") throw new Error(job.error.message);

      // Poll interval increases as job takes longer
      const elapsed = Date.now() - start;
      const interval = elapsed < 10000 ? 1000 : elapsed < 60000 ? 5000 : 15000;
      await new Promise((resolve) => setTimeout(resolve, interval));
    }

    throw new Error(`Job ${jobId} timed out after ${timeout}ms`);
  }

  private async request(path: string, init: RequestInit = {}) {
    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      const response = await fetch(`${this.baseUrl}${path}`, {
        ...init,
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          "Content-Type": "application/json",
          ...init.headers,
        },
      });

      if (response.ok) return response.json();

      if (response.status === 429 || response.status >= 500) {
        if (attempt < this.maxRetries) {
          const retryAfter = parseInt(response.headers.get("Retry-After") || "0");
          const backoff = Math.max(retryAfter * 1000, Math.pow(2, attempt) * 1000);
          await new Promise((resolve) => setTimeout(resolve, backoff));
          continue;
        }
      }

      const error = await response.json();
      throw new ConversionError(error.error.code, error.error.message, response.status);
    }
  }
}

SDK Integration Examples

Node.js

const { ConvertIntoMP4 } = require("@convertintomp4/node");

const client = new ConvertIntoMP4({ apiKey: process.env.CONVERT_API_KEY });

// Simple synchronous conversion
const result = await client.convert({
  file: fs.createReadStream("input.docx"),
  outputFormat: "pdf",
});
await result.saveTo("output.pdf");

// Async conversion with webhook
const job = await client.createJob({
  input: "https://storage.example.com/video.mov",
  outputFormat: "mp4",
  options: { codec: "h264", quality: "high" },
  webhook: "https://your-app.com/webhooks/conversion",
});

console.log(`Job created: ${job.id}, status: ${job.status}`);

Python

from convertintomp4 import ConvertIntoMP4

client = ConvertIntoMP4(api_key=os.environ["CONVERT_API_KEY"])

# Convert a local file
result = client.convert(
    file=open("input.png", "rb"),
    output_format="webp",
    options={"quality": 85}
)
result.save("output.webp")

# Batch conversion
jobs = client.batch_convert(
    files=[
        {"input": "doc1.pdf", "output_format": "docx"},
        {"input": "doc2.pdf", "output_format": "docx"},
        {"input": "image.tiff", "output_format": "png"},
    ]
)

for job in jobs.wait_all(timeout=300):
    print(f"{job.id}: {job.status}")
    if job.status == "completed":
        job.save(f"output/{job.output_filename}")

Code editor showing API integration with syntax highlighting and inline documentation

Go

package main

import (
    "context"
    "fmt"
    "os"

    convertintomp4 "github.com/convertintomp4/go-sdk"
)

func main() {
    client := convertintomp4.NewClient(os.Getenv("CONVERT_API_KEY"))

    // Create a conversion job
    job, err := client.CreateJob(context.Background(), &convertintomp4.JobRequest{
        Input:        "https://storage.example.com/video.avi",
        OutputFormat: "mp4",
        Options: map[string]interface{}{
            "codec":   "h264",
            "quality": "high",
        },
    })
    if err != nil {
        panic(err)
    }

    // Wait for completion
    result, err := client.WaitForJob(context.Background(), job.ID, 5*time.Minute)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Conversion complete: %s (%d bytes)\n", result.OutputURL, result.OutputSize)
}

Common Integration Architectures

Direct Integration

The simplest architecture: your application calls the conversion API directly.

User -> Your App -> Conversion API -> Your App -> User

Best for: Small applications, prototypes, low-volume conversions.

Queue-Based Integration

For higher volumes, decouple the conversion request from the response using a message queue:

User -> Your App -> Message Queue -> Worker -> Conversion API
                                                    |
User <- Your App <- Database Update <-- Webhook <---+

Best for: Production applications with variable conversion loads and reliability requirements.

Microservice Architecture

In a microservices architecture, a dedicated conversion service handles all file format transformations:

Service A -+
Service B -+-> Conversion Microservice -> Conversion API
Service C -+         |
                     +-> Internal Queue
                     +-> Result Storage
                     +-> Metrics/Monitoring

Best for: Large applications where multiple services need conversion capabilities.

Performance Optimization

Minimize Upload Time

Compress files before uploading (if the compression does not interfere with conversion)
Use multipart uploads for large files
Upload to the nearest geographic region
Use signed URLs with direct-to-storage uploads to avoid routing through your server

Optimize Conversion Options

Not all conversions take the same amount of time. Choose settings that balance quality and speed:

Optimization	Impact	Tradeoff
Lower resolution	2-5x faster	Reduced visual quality
Faster codec preset	2-10x faster	Larger output file
Skip audio processing	10-30% faster	No audio in output
Single-pass encoding	1.5-2x faster	Less optimal bitrate
Reduced color depth	Minor speedup	Subtle color changes

Cache Converted Results

If the same files are converted repeatedly (common with image thumbnails, document previews), cache the results:

async function getConvertedFile(inputHash, outputFormat, options) {
  const cacheKey = `${inputHash}:${outputFormat}:${JSON.stringify(options)}`;

  // Check cache first
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  // Convert and cache
  const result = await conversionClient.convert({
    /* ... */
  });
  await redis.setex(cacheKey, 86400, JSON.stringify(result)); // Cache for 24 hours

  return result;
}

Monitoring and Observability

Track these metrics to ensure your conversion integration is healthy:

Conversion success rate: Target 99%+ for a healthy integration
Average conversion time: Track by format pair and file size
Error rate by type: Distinguish between client errors and server errors
Queue depth: If using async processing, monitor queue length for capacity planning
API latency (p50, p95, p99): Detect performance degradation early
Webhook delivery rate: Ensure webhooks are being received and processed

For automated conversion workflows beyond API integration, our guide on automating file conversions covers shell scripts, CI/CD pipelines, and workflow automation tools. And for understanding the full range of conversion capabilities available, explore our video converter, image converter, PDF converter, and audio converter tool pages.