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
Quand une tâche en arrière-plan se termine, nous envoyons job.succeeded ou job.failed en POST vers votre webhook_url, avec l’objet tâche dans data. Une réponse 2xx compte comme reçue ; sinon nous réessayons jusqu’à 5 fois : tout de suite, puis après 10 secondes, 1 minute, 5 minutes et 30 minutes. Chaque requête porte reimply-event-id, reimply-event-type et reimply-signature. Vérifiez que l’horodatage est récent pour bloquer les rejeux.
{ "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 transforme un PDF numérique, un document Word (DOCX) ou un fichier CSV, TSV ou JSON en Markdown, en tableaux JSON lorsqu’ils peuvent être trouvés, et en morceaux d’environ 512 jetons (options.chunk_size, de 64 à 4096). Les comptes de jetons sont approximatifs (environ 4 caractères par jeton). Les réponses PDF incluent des métadonnées par page. Les fichiers sont traités en mémoire, pas écrits sur le disque. Ingest n’exécute pas d’OCR. Un PDF sans texte extractible, ou avec moins d’environ 20 caractères par page en moyenne, renvoie 422 ocr_required_unsupported et n’est pas facturé. Le travail coûte 1 conversion. Ingest est disponible sur Growth (39 £) et Scale ; les comptes Free et Starter reçoivent 403 plan_upgrade_required avec un lien de mise à niveau.
Optimize
POST /v1/optimize réduit une image ou un PDF à options.max_bytes (un nombre d’octets, ou une taille comme "100kb"). Pour les images, options.format peut être jpg, webp ou png. Si le fichier tient déjà sous la limite, il est renvoyé tel quel. Si la limite est inatteignable, vous recevez 422 target_unreachable avec bytes_achieved et max_bytes, sans facturation. Le travail coûte 1 conversion.
MCP server
Un serveur MCP officiel est disponible en paquet npm @reimply/mcp-server. Configurez Claude Desktop, Cursor ou Windsurf avec REIMPLY_API_KEY. Il peut convertir, optimiser, ingérer, lister les conversions et lire l’usage du compte, et il accepte des chemins de fichiers locaux. Voir le README du paquet pour la configuration.
Conversions
1 fichier = 1 conversion. Les tâches vidéo et audio comptent pour 3. La taille et le temps de traitement n’ajoutent pas de conversions. Les conversions sont réservées au démarrage et remboursées en entier en cas d’échec. Voir les tarifs. GET /v1/account renvoie vos soldes. Chaque réponse /v1 authentifiée inclut Reimply-Quota-Limit (quota mensuel), Reimply-Quota-Remaining (conversions restantes sur la période) et Reimply-Quota-Reset (heure Unix de la prochaine réinitialisation mensuelle). See Tarifs.
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_largeavant toute consommation de conversions. - 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. |