A File Conversion API Built for AI Agents and LLM Workflows

Every agent framework demo starts with clean text. Production agents start with a PDF scan, a HEIC photo, a WAV recording or a PowerPoint deck, and the first thing the agent has to do is turn that into something its next step accepts. file-convert.online offers two ways to do that from code or from a model: a REST API described by an OpenAPI document, and an MCP server that wraps it as tools. This article explains when to use which, and what the agent-facing design decisions are.

Why agents need format conversion

• Input normalisation: vision and document models accept a short list of formats. Converting HEIC to JPG, TIFF to PNG or DOCX to PDF before the model sees the file removes a whole class of failures.
• Output delivery: the user wants the summary as a DOCX, the chart as a PNG, the transcript as a PDF. The model produces text; a conversion step produces the file.
• Pipeline glue: transcription APIs want MP3 or WAV at a given rate, e-readers want EPUB, print shops want PDF. Agents that can convert stop asking humans to do it.
• Archives: a ZIP from a customer has to be extracted before anything can be read.

REST API or MCP tools?

Both hit the same gateway, the same account and the same credits. Choose by who is writing the integration.

• Use the REST API when your own code orchestrates the work: a backend job, a LangChain or LlamaIndex tool you define, a serverless function. You control retries, timeouts and storage. The contract is at https://file-convert.online/api/mcp/openapi.json.
• Use the MCP server when a model is the orchestrator: Claude Code or Cursor in a developer's editor, Claude Desktop or ChatGPT for a knowledge worker, n8n's AI Agent node in an automation. The server ships tool descriptions and instructions written for the model, so it behaves correctly without prompt engineering on your side.
• Use both when a product embeds an agent: the agent converts through MCP during a conversation, while your backend uses REST to extend retention, list history or manage keys.

Authentication and keys

A single key type serves both surfaces. Keys look like fc_live_<id>_<secret>, are created on the account page (file-convert.online/account/api-keys) or with POST /api/identity/v1/api-keys from a signed-in session, and are sent as Authorization: Bearer fc_live_... (or X-Api-Key). They are stored hashed; revocation propagates within a minute. A key is bound to the account that created it, so usage and credits are attributed to that account whether the call came from curl, from Claude or from n8n.

The workflow on the wire

For a REST client the full flow is four calls; the MCP server folds the first two into convert_file.

# 1. upload
curl -s -X POST https://file-convert.online/api/file/v1/file \
  -H "Authorization: Bearer $FC_API_KEY" -F "[email protected]"
# -> data.uid = <file_uid>

# 2. start (formats by id from /api/conversion/v1/file_formats; docx->pdf are document formats)
curl -s -X POST https://file-convert.online/api/conversion/v1/conversion \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"file_uid":"<file_uid>","format_type_id":4,"source_format_id":<docx_id>,"target_format_id":<pdf_id>}'
# -> data.uid = <conversion_uid>

# 3. poll
curl -s https://file-convert.online/api/conversion/v1/conversion/uid/<conversion_uid>/status \
  -H "Authorization: Bearer $FC_API_KEY"
# -> {"status":"Completed"} ; the conversion object carries converted_file_uid

# 4. download (the link needs no auth: the unguessable file id is the capability)
curl -s -o report.pdf https://file-convert.online/api/file/v1/file/download/<converted_file_uid>

Statuses are Pending, Processing, Completed and Failed. Failed conversions include the reason and refund their credits. Results are downloadable for about an hour; PUT /api/file/v1/file/uid/{uid}/retention extends that to as many as 14 days for a specific file.

Credits and rate limits, designed for unattended callers

Agents run unattended, so the failure modes have to be legible to a model rather than to a human reading a dashboard. Credits are reserved when a job starts and released if it fails. Costs are fixed per category (image 1, document, audio, archive and ebook 2, video 5), so an agent can estimate a batch before starting it. Free accounts receive 10 credits per day whenever their balance is empty; the daily grant is applied on the API path too, so a brand-new key can convert without visiting the website first. Rate limits are per minute and returned in X-RateLimit headers with Retry-After on 429; the MCP server translates all of this into plain-language tool errors.

Four agent workflows that use it

1. Inbox to knowledge base: an agent watches a mailbox, converts attachments (DOCX, PPTX, HEIC) to PDF and PNG, and files them in a document store with a summary.
2. Voice notes to tickets: recordings arrive as M4A or WAV, are converted to MP3, transcribed, and turned into tickets with the audio attached.
3. Sales collateral on demand: a chat agent assembles a proposal as HTML, converts it to PDF and DOCX, and returns both links to the rep.
4. Content operations: an editorial agent converts author submissions (ODT, RTF, EPUB) into the house format before running its style checks.

Getting started

Create an account, generate a key at file-convert.online/account/api-keys, and either read the OpenAPI document at https://file-convert.online/api/mcp/openapi.json or add the MCP server to your client with the setup guide at file-convert.online/blog/add-file-conversion-mcp-server-to-claude-cursor-vscode. The README at file-convert.online/blog/file-convert-mcp-server-readme lists every tool, limit and security control.