HTTP API Reference¶

Koharu exposes a local HTTP API under:

http://127.0.0.1:<PORT>/api/v1

This is the same API used by the desktop UI and the headless Web UI.

Runtime model¶

Important current behavior:

• the API is served by the same process as the GUI or headless runtime
• the server binds to 127.0.0.1 by default; use --host to bind elsewhere
• the API and MCP server share the same loaded project, models, and pipeline state
• when no --port is provided, Koharu chooses a random local port
• everything except /api/v1/downloads, /api/v1/operations, and /api/v1/events returns 503 Service Unavailable until the app finishes bootstrapping

Resource model¶

The API is project-centric. A single project is open at a time and contains:

• a list of Pages indexed by PageId
• per-page Nodes (image layers, masks, text blocks) referenced by NodeId
• a content-addressed Blob store that holds raw image bytes by Blake3 hash
• a Scene snapshot built from those pieces, advanced by an epoch counter
• a history of Op mutations that can be undone or redone

Mutations always go through the history layer (POST /history/apply) so the scene, autosave, and event subscribers stay in sync.

Common response shapes¶

Frequently used response types include:

• MetaInfo — app version and ML device label
• EngineCatalog — installable engine ids per pipeline stage
• ProjectSummary — id, name, path, page count, last opened
• SceneSnapshot — { epoch, scene }
• LlmState — current LLM load state (status, target, error)
• LlmCatalog — local + provider models grouped by family
• JobSummary — { id, kind, status, error }
• DownloadProgress — package id, byte counts, status

Endpoints¶

Meta¶

Fonts¶

Projects¶

Every project lives under the managed {data.path}/projects/ directory; clients never supply filesystem paths.

POST /projects/current/export accepts { format, pages? } where format is one of khr, psd, rendered, inpainted. When the format produces multiple files, the response is application/zip.

Pages¶

role is segment or brushInpaint. POST /pages accepts an optional replace=true field; the import is filename-sorted using natural order.

Scene and blobs¶

/scene.bin includes the current epoch in the x-koharu-epoch response header.

History (mutations)¶

All scene mutations go through here. Each response returns { epoch }.

Op is the discriminated union that covers add/remove/update node, add/remove page, batch, and other scene transitions. The body is the JSON-tagged variant.

Pipelines¶

Body fields:

• steps — engine ids to run in order (validated against the registry)
• pages — optional subset of PageIds; omit to process the whole project
• region — optional bounding box for the inpainter (repair-brush flow)
• targetLanguage, systemPrompt, defaultFont — optional per-run overrides

The response carries an operationId. Progress and completion arrive on /events as JobStarted, JobProgress, JobWarning, and JobFinished.

Operations¶

/operations is the unified registry for in-flight and recently-completed jobs (pipelines + downloads).

Downloads¶

modelId is a package id declared via declare_hf_model_package! (e.g. "model:comic-text-detector:yolo-v5"). The response is { operationId } reusing the package id.

LLM control¶

The loaded model is a singleton resource at /llm/current.

PUT /llm/current accepts an LlmLoadRequest:

• provider targets — { kind: "provider", providerId, modelId }
• local targets — { kind: "local", modelId }
• optional options { temperature, maxTokens, customSystemPrompt }

PUT /llm/current returns 204 once the load task is queued. The actual ready state is published as LlmLoaded on /events.

Config¶

AppConfig exposes top-level data, http, pipeline, and providers:

• data.path — local data directory used for runtime, model cache, and projects
• http { connectTimeout, readTimeout, maxRetries } — shared HTTP client used by downloads and provider-backed requests
• pipeline { detector, fontDetector, segmenter, bubbleSegmenter, ocr, translator, inpainter, renderer } — engine id selected for each stage
• providers[] { id, baseUrl?, apiKey? } — saved API keys round-trip as the redacted placeholder "[REDACTED]"; never the raw secret

Built-in provider ids:

• openai
• gemini
• claude
• deepseek
• deepl
• google-translate
• caiyun
• openai-compatible

API keys are stored in the platform credential store, not in config.toml. PATCHing apiKey: "" clears the saved key; PATCHing "[REDACTED]" leaves it unchanged. The dedicated /config/providers/{id}/secret routes are the explicit, non-PATCH way to manage one provider's secret.

Events stream¶

Koharu exposes a Server-Sent Events stream at:

GET /events

Behavior:

• a fresh connection (no Last-Event-ID header) starts with a Snapshot event holding the current jobs and downloads registries
• on reconnect, the server replays buffered events with seq > Last-Event-ID in order; if the requested id has scrolled out of the ring, the server re-sends a Snapshot
• each live event is emitted with its seq as the SSE id: field
• a 15-second keep-alive is maintained

Event variants currently include:

• Snapshot — full state seed for fresh and lag-recovery clients
• JobStarted, JobProgress, JobWarning, JobFinished — pipeline job lifecycle
• DownloadProgress — package download progress ticks
• ConfigChanged — config was applied via PATCH /config or a secret route
• LlmLoaded, LlmUnloaded — LLM lifecycle transitions
• SceneAdvanced — emitted when a scene mutation advances the epoch

Typical workflow¶

The normal API order for one new project is:

1. POST /projects — create the project
2. POST /pages (or /pages/from-paths from Tauri) — import images
3. PUT /llm/current — load a translation model (local or provider)
4. POST /pipelines — kick off detect → ocr → translate → inpaint → render
5. tail GET /events until JobFinished
6. POST /projects/current/export with format = "rendered" or "psd"

For finer control, post POST /history/apply with explicit Op payloads instead of running a full pipeline.

If you want agent-oriented access instead of HTTP endpoint orchestration, see MCP Tools Reference.