API documentation
Base URL https://reimply.com/v1. Requests and replies are JSON unless you send a multipart file or ask for raw bytes. The machine-readable spec is at /v1/openapi.json.
Authentication
Create keys in your account. A key is shown once, so store it in a secret manager. Send it as Authorization: Bearer rmk_... (or X-API-Key). You can name keys, see the usage of each and revoke them at any time.
Your first request
curl https://reimply.com/v1/convert \
-H "Authorization: Bearer $REIMPLY_API_KEY" \
-H "Accept: application/octet-stream" \
-F "file=@file.png" \
-F "to=jpg" \
-F 'options={"quality":85}' \
-o file.jpgimport { readFile, writeFile } from 'node:fs/promises'
const form = new FormData()
form.append('file', new Blob([await readFile('file.png')]), 'file.png')
form.append('to', 'jpg')
form.append('options', JSON.stringify({"quality":85}))
const res = await fetch('https://reimply.com/v1/convert', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.REIMPLY_API_KEY}` },
body: form,
})
const job = await res.json()
if (!res.ok) throw new Error(job.error.message)
for (const o of job.outputs) {
const file = await fetch(o.url)
await writeFile(o.name, Buffer.from(await file.arrayBuffer()))
}
console.log(job.id, 'used', job.credits.charged, 'credit(s)')import os, requests
with open("file.png", "rb") as f:
res = requests.post(
"https://reimply.com/v1/convert",
headers={"Authorization": f"Bearer {os.environ['REIMPLY_API_KEY']}"},
files={"file": f},
data={"to": "jpg", "options": '{"quality":85}'},
)
job = res.json()
res.raise_for_status()
for o in job["outputs"]:
with open(o["name"], "wb") as out:
out.write(requests.get(o["url"]).content)
print(job["id"], "used", job["credits"]["charged"], "credit(s)")With Accept: application/octet-stream and a single result of 4 MB or less you get the file bytes back, with the job id in x-reimply-job and the conversions used in x-reimply-conversions. Authenticated replies also send Reimply-Quota-Limit, Reimply-Quota-Remaining and Reimply-Quota-Reset. Otherwise the reply is a job object:
{
"object": "job",
"id": "job_8sVJ0m1Yp2xq",
"operation": "convert",
"status": "succeeded",
"mode": "sync",
"processing_seconds": 0.42,
"input_bytes": 1048576,
"conversions": { "reserved": 1, "charged": 1 },
"outputs": [
{ "index": 0, "name": "screenshot.jpg", "size": 182311, "content_type": "image/jpeg",
"url": "https://reimply.com/v1/files/..." }
],
"expires_at": "2026-11-19T15:04:05.000Z",
"error": null
}Sending files
Three ways, for any endpoint:
- Multipart: a
filefield (or severalfiles), withto,options(a JSON string),asyncandwebhook_urlas fields. Up to 4 MB in total. - A URL:
{"input": "https://..."}or{"input": {"url": "https://...", "filename": "a.heic"}}. We download it (up to 5 redirects). Private and local addresses are refused. - A presigned upload for anything bigger:
POST /v1/uploads, PUT the bytes, then pass{"upload_id": "upl_..."}. An upload can be used once and is deleted after 60 minutes.
# 1. Ask for an upload URL
curl https://reimply.com/v1/uploads \
-H "Authorization: Bearer $REIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename": "talk.mov", "size": 52428800}'
# 2. PUT the bytes to the "url" from the reply, with its "headers"
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/quicktime" --data-binary @talk.mov
# 3. Start the job with the upload id and a webhook
curl https://reimply.com/v1/convert \
-H "Authorization: Bearer $REIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"upload_id": "upl_..."}, "to": "mp4", "webhook_url": "https://example.com/hooks/reimply"}'import { readFile, stat } from 'node:fs/promises'
const auth = { Authorization: `Bearer ${process.env.REIMPLY_API_KEY}` }
const { size } = await stat('talk.mov')
const up = await (await fetch('https://reimply.com/v1/uploads', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ filename: 'talk.mov', size }),
})).json()
await fetch(up.url, { method: 'PUT', headers: up.headers, body: await readFile('talk.mov') })
const res = await fetch('https://reimply.com/v1/convert', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ input: { upload_id: up.id }, to: 'mp4', async: true }),
})
let job = await res.json() // 202, status "queued"
while (job.status === 'queued' || job.status === 'running') {
await new Promise((r) => setTimeout(r, 3000))
job = await (await fetch(`https://reimply.com/v1/jobs/${job.id}`, { headers: auth })).json()
}
console.log(job.status, job.outputs)import os, time, requests
auth = {"Authorization": f"Bearer {os.environ['REIMPLY_API_KEY']}"}
size = os.path.getsize("talk.mov")
up = requests.post("https://reimply.com/v1/uploads", headers=auth, json={"filename": "talk.mov", "size": size}).json()
with open("talk.mov", "rb") as f:
requests.put(up["url"], headers=up["headers"], data=f)
job = requests.post("https://reimply.com/v1/convert", headers=auth,
json={"input": {"upload_id": up["id"]}, "to": "mp4", "async": True}).json()
while job["status"] in ("queued", "running"):
time.sleep(3)
job = requests.get(f"https://reimply.com/v1/jobs/{job['id']}", headers=auth).json()
print(job["status"], job["outputs"])Sync and async jobs
A job runs synchronously and returns its result when the input is known to be 4 MB or less. It runs in the background, answering 202 with a Location header, when you set "async": true, set a webhook_url, or send a presigned upload over 4 MB. Poll GET /v1/jobs/{id} or wait for the webhook. Status goes queued, running, then succeeded or failed. Results and inputs are deleted 60 minutes after the job; links in the job expire at expires_at.
Webhooks
Quando un lavoro in background finisce, inviamo job.succeeded o job.failed in POST al tuo webhook_url, con l’oggetto del lavoro in data. Una risposta 2xx conta come consegnata; altrimenti ritentiamo fino a 5 volte: subito, poi dopo 10 secondi, 1 minuto, 5 minuti e 30 minuti. Ogni richiesta porta reimply-event-id, reimply-event-type e reimply-signature. Controlla che il timestamp sia recente per bloccare i replay.
{ "id": "evt_...", "type": "job.succeeded", "created": 1763550000, "data": { "object": "job", "id": "job_...", ... } }import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: the exact request body as a string. header: the reimply-signature header.
export function verifyReimply(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
const a = Buffer.from(expected)
const b = Buffer.from(parts.v1 || '')
return a.length === b.length && timingSafeEqual(a, b)
}import hmac, hashlib, time
def verify_reimply(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
if not t or abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Send yourself a signed test event with POST /v1/webhooks/test {"url": "https://..."}.
Endpoints
| POST | /v1/convert | Convert one file: {"input", "to", "options"}. Options: quality, dpi, height, crf, fps, audio_bitrate. |
| POST | /v1/compress | Compress an image, PDF, audio or video. options.target_size ("200kb", "1mb") hits an exact size for images and PDFs. |
| POST | /v1/merge | Merge 2 to 20 PDFs (images are added as pages) in the order given. |
| POST | /v1/split | Split a PDF: {"options": {"mode": "each"}} or {"mode": "ranges", "ranges": "1-3,4-"}. |
| POST | /v1/organize | Reorder, remove and rotate pages: {"options": {"pages": [3,1,2], "rotate": {"1": 90}}}. |
| POST | /v1/images-to-pdf | 1 to 20 images into one PDF. options.page_size: "a4" or "fit". |
| POST | /v1/pdf-to-images | Render pages as png, jpg or webp. options.format, options.dpi (36 to 300). |
| POST | /v1/ocr | Text from an image or a scanned PDF (up to 30 pages). options.lang: eng, deu, fra, spa, ita, por, nld. |
| POST | /v1/ingest | Digital PDF, DOCX, CSV, TSV or JSON to Markdown, tables and chunks. Growth and Scale only. options.chunk_size (default 512). |
| POST | /v1/optimize | Shrink an image or PDF to options.max_bytes. Returns 422 target_unreachable and charges nothing if the cap cannot be reached. |
| POST | /v1/uploads | Get a presigned PUT URL for files over 4 MB. |
| GET | /v1/jobs/{id} | Job status, conversions and signed output links. |
| GET | /v1/jobs | Your recent jobs. |
| GET | /v1/jobs/{id}/outputs/{n} | Redirects to output n. |
| GET | /v1/account | Plan, conversion balances, usage and quota headers. |
| POST | /v1/webhooks/test | Send a signed test event to a URL. |
| GET | /v1/conversions | Every supported format pair. No key needed. |
| GET | /v1/openapi.json | The OpenAPI 3.1 description. No key needed. |
Ingest
POST /v1/ingest trasforma un PDF digitale, un documento Word (DOCX) o un file CSV, TSV o JSON in Markdown, tabelle JSON quando si trovano, e spezzoni di circa 512 token (options.chunk_size, da 64 a 4096). Il conteggio dei token è approssimativo (circa 4 caratteri per token). Le risposte PDF includono metadati per pagina. I file sono elaborati in memoria, non scritti su disco. Ingest non esegue OCR. Un PDF senza testo estraibile, o con meno di circa 20 caratteri per pagina in media, restituisce 422 ocr_required_unsupported e non viene addebitato. Il lavoro costa 1 conversione. Ingest è disponibile su Growth (39 £) e Scale; gli account Free e Starter ricevono 403 plan_upgrade_required con un link di aggiornamento.
Optimize
POST /v1/optimize riduce un’immagine o un PDF a options.max_bytes (byte, o una dimensione come "100kb"). Per le immagini, options.format può essere jpg, webp o png. Se il file è già sotto il limite, viene restituito così com’è. Se il limite non è raggiungibile, ricevi 422 target_unreachable con bytes_achieved e max_bytes, senza addebito. Il lavoro costa 1 conversione.
MCP server
Un server MCP ufficiale è disponibile come pacchetto npm @reimply/mcp-server. Configura Claude Desktop, Cursor o Windsurf con REIMPLY_API_KEY. Può convertire, ottimizzare, acquisire, elencare le conversioni e leggere l’uso dell’account, e accetta percorsi di file locali. La configurazione è nel README del pacchetto.
Conversioni
1 file = 1 conversione. I lavori video e audio valgono 3. Dimensione e tempo di elaborazione non aggiungono conversioni. Le conversioni vengono riservate all’avvio e rimborsate per intero in caso di errore. Vedi i prezzi. GET /v1/account restituisce i saldi. Ogni risposta /v1 autenticata include Reimply-Quota-Limit (quantitativo mensile), Reimply-Quota-Remaining (conversioni rimaste in questo periodo) e Reimply-Quota-Reset (ora Unix del prossimo reset mensile). See Prezzi.
Limits and rate limits
- Uploads up to 1 GB. Processing limits: images 100 MB, PDFs 250 MB, documents and data 25 MB, audio 500 MB, video 500 MB and 10 minutes. Larger files are refused with
file_too_largeprima di usare conversioni. - Synchronous requests and inline results: up to 4 MB.
- A job can run for about 4 minutes; longer jobs fail and are not charged.
- Ingest and optimize run in memory and are not written to disk during processing.
- Requests a minute per key: Free 30, Starter 120, Growth 300, Scale 600. Every reply has
x-ratelimit-limit,x-ratelimit-remainingandx-ratelimit-reset; a 429 hasretry-after. - Background jobs at once: Free 1, Starter 3, Growth 10, Scale 25.
Idempotency
Send Idempotency-Key: any-unique-string on POST requests to retry safely. For 24 hours the same key with the same request returns the first reply (with idempotent-replayed: true) instead of running and charging again. The same key with a different request gets 422 idempotency_key_reused.
Errors
Errors are JSON: {"error": {"code": "insufficient_credits", "message": "...", "status": 402}}.
| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | The body or an option is missing or wrong. The message says which. |
| unauthorized | 401 | No API key was sent. |
| invalid_api_key | 401 | The key is unknown or revoked. |
| insufficient_credits | 402 | Not enough conversions for this job. Upgrade your plan. |
| forbidden | 403 | The key cannot access this resource. |
| plan_upgrade_required | 403 | This endpoint needs a higher plan. The message includes an upgrade link. |
| not_found | 404 | Unknown endpoint, job or file. |
| upload_not_found | 404 | Unknown, expired or already used upload_id. |
| idempotency_in_progress | 409 | A request with this Idempotency-Key is still running. |
| file_too_large | 413 | Over your plan cap, or over the processing limit for this file type. |
| unsupported_file_type | 415 | This endpoint does not take that kind of file. |
| file_mismatch | 415 | The file contents do not match its extension. |
| unsupported_conversion | 422 | That format pair is not available. See /v1/conversions. |
| conversion_failed | 422 | The file could not be processed (damaged, encrypted or empty). No conversions are charged. |
| ocr_required_unsupported | 422 | The PDF looks scanned or image-only. Ingest does not run OCR in this version, and nothing is charged. |
| target_unreachable | 422 | The byte cap could not be reached. The error includes bytes_achieved and max_bytes, and nothing is charged. |
| source_blocked | 422 | The source URL points to a private or local address. |
| source_fetch_failed | 422 | The source URL could not be downloaded. |
| idempotency_key_reused | 422 | The Idempotency-Key was used with a different request. |
| rate_limited | 429 | Too many requests a minute for this key. Wait for Retry-After seconds. |
| concurrency_limit | 429 | Too many background jobs running at once for your plan. |
| internal_error | 500 | Something went wrong on our side. Retrying is safe with an Idempotency-Key. |
| storage_unavailable | 503 | File storage is temporarily unavailable. |
| billing_unavailable | 503 | Purchasing is temporarily unavailable. |