REST API
The HTTP API behind the studio, for scripts and automation.
1. Basics
The studio talks to its server through a JSON API at http://localhost:8124/api. You can use it for scripts, but it is the app's own API, not a stable public one: routes and fields can change between releases.
Authentication: requests from the same machine (to localhost, 127.0.0.1 or [::1], without proxy headers) need nothing. Everything else sends the access token as Authorization: Bearer <token> or X-XianScan-Token: <token>. Cross-origin (CORS) access is only granted to browser extensions.
curl -H "Authorization: Bearer $XIANSCAN_TOKEN" http://192.168.1.20:8124/api/books2. Library
| Method & Route | Description |
|---|---|
GET /api/books | List books |
POST /api/books | Create a book |
GET, PATCH, DELETE /api/books/:id | Read, edit or delete a book |
POST /api/books/:id/chapters | Create a chapter |
POST /api/books/:id/chapters/reorder | Change chapter order |
POST, DELETE /api/books/:id/clear-progress | Reset translations of the whole book |
GET, PATCH, DELETE /api/chapters/:id | Read, edit or delete a chapter |
POST /api/chapters/:id/pages | Upload page images (multipart/form-data) |
POST /api/chapters/:id/pages/reorder | Change page order |
POST /api/chapters/:id/reslice | Re-slice the chapter |
GET /api/chapters/:id/download | Chapter ZIP. Pages that could not be included are listed in MISSING_PAGES.txt and the x-missing-pages header |
GET, PATCH, DELETE /api/pages/:id | Read, edit or delete a page |
GET /api/pages/:id/file?kind=output | Page image: output, cleaned, original, thumb or annotated |
PATCH /api/pages/:id/regions/:regionId | Edit one text region's translation or its lettering (role: dialogue or accent) |
GET /api/covers/:bookId/file?w=512 | Book cover, resized (80 to 1600 px) |
3. Translation
| Method & Route | Description |
|---|---|
POST /api/chapters/:id/translate | Translate a chapter |
GET /api/chapters/:id/translate | Progress as a server-sent event stream (404 when nothing is running) |
DELETE /api/chapters/:id/translate | Cancel |
POST /api/pages/:id/translate | Translate one page |
POST /api/pages/:id/typeset | Redraw one page's text |
POST /api/pages/:id/reset | Clear one page's progress |
GET, POST, DELETE /api/batch | Queue state, add chapters, clear |
POST /api/batch/:action | pause, resume, skip, cancel, clear or remove |
GET /api/batch/events | Queue updates as an event stream |
POST /api/translate-text | Translate a piece of text with the active provider |
GET, POST, PATCH /api/glossary | List, add or bulk-edit glossary terms |
PUT, DELETE /api/glossary/:id | Edit or delete one term |
POST /api/glossary/import, GET /api/glossary/export | CSV import and export |
GET, POST /api/glossary/packs | List theme packs, choose which are on |
4. Settings and System
| Method & Route | Description |
|---|---|
GET, PATCH /api/settings | Read or change settings |
GET, POST /api/system/providers | Translation providers; /models lists a provider's models, /test tests it |
GET, POST /api/system/hardware | Active device and GPUs; switch device (see GPU Acceleration) |
GET /api/system/telemetry | CPU, memory, GPU use and running jobs |
GET /api/system/version | Installed version and latest release |
GET, POST /api/system/storage | Disk usage; actions purge-orphaned, clear-cache, clear-all |
GET, POST /api/books/:id/storage | A book's disk usage; action prune-cache clears its thumbnails |
GET, POST /api/system/fonts | List or upload fonts (.ttf, .otf) |
GET, DELETE /api/system/fonts/:id | Read or remove an imported font |
POST /api/system/fonts/:id/variants, DELETE /api/system/fonts/:id/variants/:variantId | Add or remove a weight |
GET /api/system/fonts/system | Fonts installed on the computer |
GET /api/system/fonts/coverage | Which font is used for each script, and the letters each accent font lacks (accent) |
GET /api/system/fonts/book-scripts | Scripts your books are typeset in |
POST /api/typeset/preview | Render an exact typesetting preview (optional mode: accent draws the text as an accent callout) |
GET, PATCH /api/system/access | LAN state, token and addresses; turn LAN on or off (after a restart) |
POST /api/system/access/token/regenerate | Replace the access token |
POST /api/auth/unlock, GET /api/auth/status, POST /api/auth/logout | Browser session |
GET /api/mihon/* | Routes for the Mihon extension (see Extension Architecture) |
5. Internal Engine API (port 8123)
The Rust engine has its own API on 127.0.0.1:8123, used only by the web server. It refuses browser requests and needs a per-run secret header, so you cannot and should not call it directly; use the web API above.
Its limits also apply to everything you upload: each image up to 100 megapixels and 65,535 px per side, a re-slice up to 400 images and a 200-megapixel canvas. Oversized requests are answered with 413, undecodable or oversized images with 422.