Developer API

Convert any file with a single API call

One simple endpoint, every format. Built on the same engine that powers our online tools.

Quickstart

Pick an endpoint and language to see a working request.

curl https://api.toolnest.app/v1/convert \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "file=@photo.png" \
  -F "to=jpg" \
  -F "quality=85" \
  -o converted.jpg

Endpoints

Method	Path	Description
POST	/v1/convert	Convert any supported file format.
POST	/v1/compress	Compress images, PDFs and videos.
POST	/v1/ocr	Extract text from a single image (AI).
POST	/v1/ocr/batch	Extract text from up to 5 images, with combined output.
POST	/v1/enhance	AI upscale and enhance images.
GET	/v1/usage	Inspect your current quota usage.

API playground

Pick an endpoint, upload files, tweak parameters and call it live — the JSON response appears inline. No key required while you're signed in. Settings are saved to this browser; create presets for quick switching.

Presets:None saved yet

Request — POST /v1/ocr/batch

Authentication

Drop your files here

or click to browse from your device

Up to 10 files

maxFilesoutputFormat

mergeMode

combined_text preview

--- page-1.png ---
<text from page-1.png>

--- page-2.png ---
<text from page-2.png>

Fix before sending

Add at least one file.

// Response will appear here after you send a request.

Ready-to-copy curl — every mergeMode × outputFormat combo

per-page

both

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"per-page\",\"outputFormat\":\"both\",\"maxFiles\":5}"

per-page

text

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"per-page\",\"outputFormat\":\"text\",\"maxFiles\":5}"

per-page

structured

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"per-page\",\"outputFormat\":\"structured\",\"maxFiles\":5}"

concatenated

both

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"concatenated\",\"outputFormat\":\"both\",\"maxFiles\":5}"

concatenated

text

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"concatenated\",\"outputFormat\":\"text\",\"maxFiles\":5}"

concatenated

structured

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"concatenated\",\"outputFormat\":\"structured\",\"maxFiles\":5}"

none

both

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"none\",\"outputFormat\":\"both\",\"maxFiles\":5}"

none

text

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"none\",\"outputFormat\":\"text\",\"maxFiles\":5}"

none

structured

curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "options={\"mergeMode\":\"none\",\"outputFormat\":\"structured\",\"maxFiles\":5}"

Batch OCR — multi-page documents

Upload up to 5 images in a single call. The server runs OCR on each page and returns per-image metadata plus a combined_text field that joins every page in upload order — perfect for scanned multi-page documents.

POST /v1/ocr/batch

# Send up to 5 images in one request — server returns per-image
# results plus a combined_text field.
curl https://api.toolnest.app/v1/ocr/batch \
  -H "Authorization: Bearer $TOOLNEST_KEY" \
  -F "files[]=@page-1.png" \
  -F "files[]=@page-2.png" \
  -F "files[]=@page-3.png" \
  -F "merge=true"

Example response (200 OK)

{
  "results": [
    {
      "name": "page-1.png",
      "text": "Invoice #1024\nTotal: $48.20",
      "blocks": [
        { "text": "Invoice #1024", "type": "heading", "confidence": 0.98 },
        { "text": "Total: $48.20",  "type": "paragraph", "confidence": 0.94 }
      ],
      "confidence": 0.96,
      "language": "en",
      "word_count": 5
    },
    { "name": "page-2.png", "text": "...", "blocks": [], "confidence": 0.91, "language": "en", "word_count": 142 }
  ],
  "combined_text": "--- page-1.png ---\nInvoice #1024\nTotal: $48.20\n\n--- page-2.png ---\n..."
}

Errors

Every error response uses the same JSON envelope so your client can branch onerror.codewithout parsing free-form messages.

Status	Code	When it happens
400	invalid_request	Missing or malformed parameters (e.g. unsupported format).
401	unauthorized	Missing, malformed or revoked API key.
402	quota_exhausted	Plan quota or AI credits used up — upgrade or top up.
413	file_too_large	Uploaded file exceeds the per-request size limit.
415	unsupported_media	File type cannot be processed by this endpoint.
429	rate_limited	Too many requests in the current window. See Retry-After.
500	internal_error	Unexpected server error. Safe to retry with backoff.

Example responses

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714521600
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after_seconds": 12,
    "request_id": "req_77be0e..."
  }
}

Rate limits

Every response includes X-RateLimit-Limit,X-RateLimit-Remaining andX-RateLimit-Reset headers. When you hit the cap you get a 429 with a Retry-After hint.

Plan	Sustained	Burst	Monthly quota
Free	30 req/min	60 burst	500 conversions / month
Starter	120 req/min	240 burst	10,000 conversions / mo
Pro	600 req/min	1,200 burst	100,000 conversions / mo
Enterprise	Custom	Custom	Custom

API keys

Create keys to authenticate requests. Keep them secret — anyone with your key can use your quota.

Fast

Most conversions complete in under a second.

Secure

Files auto-deleted after 1 hour. Encrypted in transit.

Simple

REST endpoints, native SDKs for Node, Python, Go.