Runemic API documentation.
Send a page image to POST /v1/ocr and get its text back in reading order, as Markdown or plain text.
Preview 2,500 free credits for new accounts.
Quick start
Create a key
Sign in to the Runemic Console with GitHub or Hugging Face and create a key under API keys. It is shown once.
Store it
Keep it out of your code:
export RUNEMIC_API_KEY="rk_live_…"Send a page
PNG, JPEG, WebP or GIF, up to 4 MB.
cURL
curl https://api.runemic.com/v1/ocr \ -H "Authorization: Bearer $RUNEMIC_API_KEY" \ -F "file=@page.png" \ -F "model=preview-gemma-4"
Python
import os, requests resp = requests.post( "https://api.runemic.com/v1/ocr", headers={"Authorization": f"Bearer {os.environ['RUNEMIC_API_KEY']}"}, files={"file": open("page.png", "rb")}, data={"model": "preview-gemma-4"}, ) resp.raise_for_status() print(resp.json()["text"])
JavaScript (Node 18+)
import { readFile } from "node:fs/promises"; const form = new FormData(); form.append("file", new Blob([await readFile("page.png")], { type: "image/png" }), "page.png"); form.append("model", "preview-gemma-4"); const res = await fetch("https://api.runemic.com/v1/ocr", { method: "POST", headers: { Authorization: `Bearer ${process.env.RUNEMIC_API_KEY}` }, body: form, }); console.log((await res.json()).text);
Authentication
Every request to /v1/ocr needs your key in the Authorization header: Authorization: Bearer rk_live_…. Keys can be renamed and revoked in the console; a revoked key stops working immediately. Never put a key in a website or app that other people can inspect; call the API from your server.
POST /v1/ocr
Reads one page. Send multipart/form-data with a file, or JSON with an image.
| Parameter | Type | Description |
|---|---|---|
file | file | The page image (multipart). PNG, JPEG, WebP or GIF, max 4 MB. |
image | string | JSON alternative: a base64 data URI (data:image/png;base64,…) or a public https:// URL. |
model | string | Optional. A model ID from GET /v1/models. Default preview-gemma-4. |
format | string | Optional. markdown (default: headings, lists and tables) or text (plain text). |
instructions | string | Optional, up to 300 characters of extra guidance, for example "Only return the table". |
stream | boolean | Optional. true sends the text while the model writes it, as server-sent events (see below). |
Streaming
A full page takes several seconds to write out. With stream set, the response is text/event-stream: delta events carry pieces of text as they are written, then one done event carries the full result, with the same fields as a normal response. If the model fails, you get an error event instead, and you are not charged.
curl -N https://api.runemic.com/v1/ocr \ -H "Authorization: Bearer $RUNEMIC_API_KEY" \ -F "file=@page.png" \ -F "stream=true" event: delta data: {"text": "# Invoice No. 4821\n\nCity"} event: done data: {"id": "req_c28e0b7d9a4f13e65b02", "object": "ocr.result", "text": "# Invoice No. 4821 …", "usage": {…}}
JSON request
curl https://api.runemic.com/v1/ocr \ -H "Authorization: Bearer $RUNEMIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image": "https://example.com/page.jpg", "format": "text"}'
Response
{
"id": "req_7f3a9c2e41b8d05e6a17",
"object": "ocr.result",
"model": "preview-gemma-4",
"text": "# INVOICE No. 4821\n\nCity Library …",
"format": "markdown",
"usage": { "pages": 1, "credits_used": 2, "ms": 2210 },
"credits_left": 2498
}
Every response also has an X-Request-Id header that matches the request in the console's Logs.
GET /v1/models
Lists the available models and how many credits each uses per page (credits_per_page). No key needed: curl https://api.runemic.com/v1/models
| Model ID | Based on | Speed | Best for | Credits per page |
|---|---|---|---|---|
preview-gemma-4default | Google Gemma 4 26B | Balanced | Multilingual pages, right-to-left scripts | 2 |
preview-mistral-small | Mistral Small 3.1 24B | Fast | Tables, forms, invoices | 3 |
preview-llama-4-scout | Meta Llama 4 Scout | Fastest | Clean printed pages, high volume | 2 |
preview-glm-ocr | Zhipu AI GLM-OCR 0.9B | About 2 s a page* | Tables and formulas; Chinese, Japanese, Korean, Latin, Cyrillic | 2 |
preview-lightonocr-3 | LightOn LightOnOCR-3 0.8B | About 1 s a page* | Tables, forms, receipts, multi-column pages | 2 |
preview-dots-mocr | rednote hi lab dots.mocr 3B | About 3 s a page* | Multilingual pages, right-to-left scripts, tables | 2 |
preview-kdl-parser-nano | KoreaDeep KDL Frontier Parser nano 1.2B | About 1 s a page* | Korean and English documents, tables | 2 |
Gemma 4, Mistral Small and Llama 4 Scout run on Cloudflare Workers AI; the other four run on Runemic's own GPUs. *The first page after an idle spell takes a few minutes while the model starts. When Rune-1 launches it becomes a new model ID; your key and code stay the same.
POST /v1/translate
Translates text, for example the text /v1/ocr read from a page. Send JSON with the same key. The translation keeps line breaks, Markdown, numbers and names. It is made by AI and we haven't measured its accuracy: have anything important checked by someone who knows both languages.
curl https://api.runemic.com/v1/translate \ -H "Authorization: Bearer $RUNEMIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "سلام، حال شما چطور است؟", "to": "en"}'
| Parameter | Type | Description |
|---|---|---|
text | string | The text to translate, up to 20,000 characters. |
to | string | The language to translate into, as a code from GET /v1/translate/languages (no key needed): en, fa, ar, ur, hi, zh, ja, ko, ru, uk, de, fr, es, it, pt, nl, pl, tr, he, vi, id. |
from | string | Optional. The language of the text, as a code from the same list. Leave it out, or send auto, and the model works it out. |
model | string | Optional. Leave it out to use Gemma 4 26B (Google), via Runemic, with Mistral Small 3.1 and Llama 4 Scout as fallbacks. Or pick one of those three: it is then used alone. |
The answer: {"id": "req_…", "object": "translation", "from": "auto", "to": "en", "text": "…", "model": "preview-gemma-4", "usage": {"characters": 23, "credits_used": 1, "ms": 900}, "credits_left": 2484}. It costs 1 credit for every started 1,000 characters, only when it works, and counts as one page toward the daily limits. Translations show in the console under Usage and Logs. To translate an image without code, use Translate an image.
OpenAI-compatible API
Already using an OpenAI SDK, or a tool built on one? Point it at https://api.runemic.com/v1 with your Runemic key and send the page as an image in a chat message. POST /v1/chat/completions, GET /v1/models and GET /v1/models/{id} follow OpenAI's format, including streaming and error types.
from openai import OpenAI import base64, os client = OpenAI(base_url="https://api.runemic.com/v1", api_key=os.environ["RUNEMIC_API_KEY"]) image = "data:image/png;base64," + base64.b64encode(open("page.png", "rb").read()).decode() reply = client.chat.completions.create( model="preview-gemma-4", messages=[{"role": "user", "content": [ {"type": "text", "text": "Only return the table."}, # optional: how to transcribe {"type": "image_url", "image_url": {"url": image}}, ]}], ) print(reply.choices[0].message.content)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.runemic.com/v1", apiKey: process.env.RUNEMIC_API_KEY }); const stream = await client.chat.completions.create({ model: "preview-gemma-4", stream: true, messages: [{ role: "user", content: [{ type: "image_url", image_url: { url: "https://example.com/page.jpg" } }] }], }); for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
| In the request | What Runemic does with it |
|---|---|
messages | Exactly one image, as an image_url part in a user message: a data: URI or a public https URL (PNG, JPEG, WebP or GIF, up to 4 MB). Text in user messages becomes transcription instructions (up to 300 characters). System and assistant messages are ignored. |
model | A model ID from GET /v1/models. Leave it out to use the default with automatic fallback. |
stream, stream_options.include_usage | Streams chat.completion.chunk events and ends with data: [DONE], like OpenAI. |
format (Runemic extension) | markdown (default) or text. With the OpenAI SDKs, pass it as extra_body={"format": "text"} (Python) or add it to the request object (JavaScript). |
temperature, max_tokens, tools and other chat options | Accepted and ignored: the models only transcribe. |
The answer is the page's text as the assistant message. usage counts tokens; credits are counted per page, as with /v1/ocr, and shown in the extra runemic field as credits_used and credits_left. Same key, limits and billing as /v1/ocr.
Use with AI assistants (MCP)
Runemic is an MCP server, so Claude, ChatGPT, Codex, Cursor, VS Code and other assistants can read pages for you. The server address is https://mcp.runemic.com/mcp.
Add it to your assistant and it sends you to Runemic to sign in (GitHub or Hugging Face) and allow access. There is no key to copy. Pages use your Runemic credits, with the same credits per page and limits as the API.
| Assistant | How to add it |
|---|---|
| Claude (web, desktop, mobile) | Settings → Connectors → Add custom connector. Name it Runemic, paste the address, then Connect. |
| Claude Code | Run the commands below, then /mcp and choose Authenticate. |
| Codex (CLI, app, IDE) | Add the lines below; codex mcp login runemic opens the sign-in page. |
| ChatGPT | With developer mode on: Settings → Apps → Create app, paste the address and choose OAuth. |
| Cursor | Add to Cursor, or put the JSON below in ~/.cursor/mcp.json. |
| VS Code | Add to VS Code, or MCP: Add Server → HTTP and paste the address. |
| Anything else | Use the address with the Streamable HTTP transport. Clients that can't sign in can send Authorization: Bearer <your API key> instead. |
# Claude Code: add the server, then run /mcp in Claude Code to sign in claude mcp add --transport http runemic https://mcp.runemic.com/mcp # or install the plugin (the server plus a skill for local files) /plugin marketplace add runemic/runemic.github.io /plugin install runemic@runemic
# Codex: ~/.codex/config.toml [mcp_servers.runemic] url = "https://mcp.runemic.com/mcp" # then sign in once codex mcp login runemic
{
"mcpServers": {
"runemic": { "type": "http", "url": "https://mcp.runemic.com/mcp" }
}
}
| Tool | What it does |
|---|---|
read_page | Reads one page image, given as a public https URL or a data: URI (PNG, JPEG, WebP or GIF, up to 4 MB). In ChatGPT, a file you attach to the chat is passed to it directly. Optional format, model and instructions, as in POST /v1/ocr; without a model, the fastest model right now reads the page and another takes over if it fails. Returns the text, the model, the credits used and your credits left. |
upload_page | Shows a Runemic file picker in the chat (in assistants that support MCP Apps, such as Claude and ChatGPT). You choose page images from your device, even several at once, and their text is sent to the conversation. Images are read and not stored. |
create_upload_link | A one-time link for sending saved files with one command (see upload links). |
list_models | The models available now, with credits per page. |
get_account | Your credits left, today's pages and limit, and this month's usage. |
Which way to send a page depends on where it is: see getting a page to Runemic. To see or disconnect connected apps, open the console and go to Settings → Connected apps.
Files on your computer (local MCP server)
The hosted server can't see your files. For Claude Desktop, Claude Code, Codex, Cursor and other apps that run MCP servers on your computer, there is a local Runemic server: give it a path to an image, a PDF or a folder of pages and it sends them to Runemic with your API key. Large scans, HEIC and TIFF are converted first; PDFs need Poppler (brew install poppler, apt install poppler-utils).
| App | How to add it |
|---|---|
| Claude Desktop | Download runemic.mcpb and open it (or Settings → Extensions → Install extension). Paste your API key when asked; it is kept in your system's keychain. |
| Claude Code, Codex | See below (for Claude Code, set RUNEMIC_API_KEY in your shell first). |
| Cursor, VS Code, others | Add the JSON below to the app's MCP settings, with your key. Needs Node 18 or newer. |
{
"mcpServers": {
"runemic-files": {
"command": "npx",
"args": ["-y", "--package=https://runemic.com/mcp/runemic-mcp.tgz", "runemic-mcp"],
"env": { "RUNEMIC_API_KEY": "rk_live_…" }
}
}
}
# Claude Code claude mcp add runemic-files -e RUNEMIC_API_KEY=$RUNEMIC_API_KEY -- npx -y --package=https://runemic.com/mcp/runemic-mcp.tgz runemic-mcp # Codex: ~/.codex/config.toml [mcp_servers.runemic-files] command = "npx" args = ["-y", "--package=https://runemic.com/mcp/runemic-mcp.tgz", "runemic-mcp"] env = { RUNEMIC_API_KEY = "rk_live_…" }
Tools: read_file (an image, or a PDF with optional pages like 1-3,7), read_folder (every page in a folder in name order, page2 before page10, up to 50), list_models and get_account. Then ask, for example, “read the PDF in my Downloads called letter.pdf”.
Upload links
Assistants that can run commands but can't show the Runemic panel (for example Claude with code execution) can ask create_upload_link on the hosted server for a one-time link: 15 minutes, up to 20 pages, on your account. The saved file is sent with one command and the text comes back in the response. You can also open the link in a browser and choose the file. Images are read and not stored.
# the assistant asks create_upload_link for a link, then sends each saved page: curl -s -F "file=@page.png" https://mcp.runemic.com/u/<token>
Getting a page to Runemic from an assistant
An assistant can only send a tool what it writes into the tool call. It sees an image you attach as a picture, not as the file, so it can't pass the attachment on. Copying the file in as text would mean writing out hundreds of thousands of characters for one page: slow, costly and easy to get wrong. So Runemic offers a way for each situation:
| Where the page is | What to do | Works in |
|---|---|---|
On the web (public https link) | Give the assistant the link; it calls read_page. | Every assistant |
| Attached to the chat, or on your phone or computer | Ask the assistant to read it with Runemic. A Runemic panel opens in the chat; choose the same file there (several pages at once are fine). The text is sent back to the chat. | Claude, ChatGPT, VS Code and other apps with MCP Apps |
| Attached to the chat in ChatGPT | Nothing extra: ChatGPT passes the attached file to read_page. | ChatGPT |
| A file on your computer, a PDF or a folder of pages | Add the local server and give the path, e.g. “read ~/Downloads/letter.pdf”. | Claude Desktop, Claude Code, Codex, Cursor |
| A file the assistant has saved in its sandbox or terminal | The assistant asks for an upload link and sends the file with curl; the text comes back in the response. | Assistants that can run commands |
This is how MCP servers handle files in general: servers that run on your computer read file paths, hosted servers take links or offer an upload step. Runemic does both.
Privacy and billing
- Images are read and discarded, whichever way they arrive. They are never stored or used for training.
- Each page costs the same credits as through the API and is charged to the Runemic account you signed in with (or whose key you use). Failed pages are free.
- Without a chosen model, the model that is fastest right now reads the page; if it fails or doesn't start within 15 seconds, another model takes over.
- Pages read through an assistant appear in the console's Usage and Logs as “AI assistant” (or under the key's name).
- Connected apps are listed in the console under Settings → Connected apps, where you can disconnect them. Deleting your account disconnects all of them.
If something doesn't work
| What you see | What to do |
|---|---|
| The assistant asks for a link instead of opening the Runemic panel | The app may still have an older list of Runemic's tools. Disconnect Runemic and connect it again (in Claude: Settings → Connectors), then start a new chat. Apps without MCP Apps support can't show the panel; use a link, an upload link or the local server. |
| “Sign in” keeps coming back | Allow the connection on the Runemic page that opens, in the same browser where you are signed in to the console. If you cancelled, connect again. |
| The upload link request is blocked | The assistant's sandbox may not be allowed to reach mcp.runemic.com. Use the Runemic panel or the local server instead. |
| The local server says the key is missing or wrong | Set RUNEMIC_API_KEY in the server's settings (in Claude Desktop: Settings → Extensions → Runemic OCR). Never paste the key into a chat. |
| A PDF can't be read by the local server | Install Poppler (brew install poppler on macOS, sudo apt install poppler-utils on Ubuntu), or export the pages as images. |
| The connector shows an old Runemic logo | Some apps show an icon they saved earlier and refresh it later. Removing and adding the connector again usually updates it. |
Errors
Errors return JSON like {"error": {"code": "…", "message": "…"}}. Failed requests are never charged.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_image · unknown_model · invalid_format · invalid_language · missing_text | Check the request body. |
| 401 | invalid_api_key | Missing, wrong or revoked key. |
| 402 | insufficient_credits | Not enough credits left for this page. The message says how many credits the model needs and how many you have. |
| 413 · 415 | too_large · unsupported_type | PNG, JPEG, WebP or GIF up to 4 MB. PDFs are coming soon. |
| 429 | rate_limited · daily_limit | Too many requests per minute, or today's page limit reached. |
| 502 | model_error | The model failed. You are not charged; retry or pick another model. |
| 503 | capacity | Today's shared preview capacity is used up. Try again after 00:00 UTC. |
| 504 | model_timeout | The model you chose didn't answer in time. You are not charged; retry or pick another model. |
Rate limits
| Requests per minute, per account (all keys together) | 20 |
| Pages per day, per account (preview) | 500 |
| Pages per day on an account's first day, or for GitHub accounts less than 14 days old | 50 |
| Image size | 4 MB |
| Active keys per account | 10 |
Need more? Email hello@runemic.com.
Data and privacy
Images are processed by the selected model and returned to you. We never store your images or their text, and never use them for training. We keep request metadata (time, model, pages, credits used, latency, status) for your usage and billing. Read the privacy notice.
Changelog
- Preview 0.5 (latest): local MCP server for files, PDFs and folders on your computer (and a Claude Desktop extension); upload links; the fastest model reads MCP pages, with quick fallback. Credits instead of dollars: 2,500 free credits, 2–3 credits a page.
- Preview 0.4: MCP server at
https://mcp.runemic.com/mcpfor Claude, ChatGPT, Codex, Cursor and VS Code, with sign-in, plus plugins for Claude Code and Codex. - Preview 0.3: OpenAI-compatible
POST /v1/chat/completions. Without amodel, another model takes over automatically if the default fails or doesn't answer; a chosen model that doesn't answer returns504 model_timeout. Request IDs are now random (req_+ 20 characters). - Preview 0.2:
streamparameter: get the text while it is being written. Removedpreview-qwen-3.8. - Preview 0.1: public preview. Four preview models,
formatandinstructionsparameters, request IDs, console with playground and usage analytics.
Try the API
New accounts get 2,500 free credits. No card needed.