File Conversion API

Convert images (resize and reformat), CSV files (to structured JSON), HTML pages (to PDF), and DOCX documents (to PDF). Supports four conversion types controlled by the type discriminator field.

Endpoints

Free test endpoint: GET /convert/test at https://x402-conversion-api-production.up.railway.app — returns fixture data, no wallet required. Paid endpoint: POST /convert — $0.02 USDC on Base per call.

No API key required

Add X402_PRIVATE_KEY to your MCP config to enable paid calls — each request automatically settles $0.02 USDC on Base. Use the free test endpoint to confirm the response schema before enabling payments.

Parameters

Parameter	Type	Required	Default	Description
type	string	Yes	—	Conversion type: "image", "csv", "html_pdf", or "docx"
url	string	Yes	—	Source file URL (http/https, max 2048 chars, max 10MB)
format	string	No (image only)	"jpeg"	Output format: "jpeg", "png", "webp", "gif"
width	integer	No (image only)	—	Target width in pixels (1–8000)
height	integer	No (image only)	—	Target height in pixels (1–8000)

format, width, and height are only used when type is "image". They are ignored for "csv", "html_pdf", and "docx".

Example — curl

# Free test (no wallet required)
curl https://x402-conversion-api-production.up.railway.app/convert/test

# Paid call — image conversion (requires x402-fetch or x402-mcp-server)
curl -X POST https://x402-conversion-api-production.up.railway.app/convert \
  -H "Content-Type: application/json" \
  -d '{"type": "image", "url": "https://example.com/photo.jpg", "format": "png", "width": 800}'

# Paid call — DOCX to PDF conversion
curl -X POST https://x402-conversion-api-production.up.railway.app/convert \
  -H "Content-Type: application/json" \
  -d '{"type": "docx", "url": "https://example.com/document.docx"}'

Example — MCP Tool Call

“Convert this image to PNG at 800px wide: https://example.com/photo.jpg”

{
  "tool": "x402_convert_file",
  "arguments": {
    "type": "image",
    "url": "https://example.com/photo.jpg",
    "format": "png",
    "width": 800
  }
}

Returns

All conversion types return a data field containing base64-encoded output:

• type: "image" — base64-decode data to get image bytes in the requested format
• type: "csv" — base64-decode data to get a JSON array of objects (one object per row)
• type: "html_pdf" — base64-decode data to get PDF binary
• type: "docx" — base64-decode data to get PDF binary (content-document fidelity; layout, fonts, and formatting are not preserved)

DOCX conversion is content-fidelity, not layout-preserving

DOCX-to-PDF conversion preserves text, headings, tables, and embedded images. Page layout, margins, custom fonts (Calibri substituted with Liberation Sans), table formatting, headers/footers, and underlined text are not preserved. For layout-accurate conversion, use a dedicated office suite. Conversion time scales with document complexity; table-heavy documents may take 10-30 seconds.

Note

For CSV conversions, data is base64-encoded JSON — not raw JSON. Always base64-decode before parsing.

Caution

HTTP 200 with success: false indicates download or conversion failure. Check the error field for: download_error, http_error, conversion_error, output_too_large.

Error Codes

Code	Meaning
400	SSRF blocked — URL targets a private/reserved IP range
402	Payment required — x402 handshake (handled automatically by MCP server)
422	Invalid URL, unsupported type, or parameter validation failed
429	Rate limit exceeded (free test: 100/hour per IP)

HTTP 200 with success: false indicates download or conversion failure. Check the error field for: download_error, http_error, conversion_error, output_too_large.