HTTP API リファレンス¶

Koharu は次のローカル HTTP API を公開しています。

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

これはデスクトップ UI と headless Web UI が使っているのと同じ API です。

ランタイムモデル¶

現在の実装で重要な挙動は次の通りです。

API は GUI または headless ランタイムと同じプロセスで提供される
サーバーは既定で 127.0.0.1 にバインドされる。別ホストに公開したい場合は --host を使う
API と MCP サーバーは同じ読み込み済みプロジェクト、モデル、パイプライン状態を共有する
--port を指定しない場合、Koharu はランダムなローカルポートを選ぶ
/api/v1/downloads、/api/v1/operations、/api/v1/events を除く全エンドポイントは、アプリのブートストラップが完了するまで 503 Service Unavailable を返す

リソースモデル¶

API はプロジェクト中心です。一度に開けるプロジェクトは 1 つで、次のものを含みます。

PageId でインデックスされた Pages のリスト
NodeId で参照されるページごとの Nodes (画像レイヤー、マスク、テキストブロック)
画像のバイト列を Blake3 ハッシュで保存する content-addressed な Blob ストア
それらから組み立てられる Scene スナップショット (epoch カウンタで進む)
undo/redo 可能な Op 変更の履歴

すべてのシーン変更は履歴レイヤー (POST /history/apply) を経由するため、シーン、自動保存、イベント購読者は常に同期されます。

よく使うレスポンス型¶

頻出するレスポンス型には次があります。

MetaInfo — アプリバージョンと ML デバイスラベル
EngineCatalog — パイプライン段階ごとにインストール可能な engine id
ProjectSummary — id、name、path、ページ数、最終オープン日時
SceneSnapshot — { epoch, scene }
LlmState — 現在の LLM 読み込み状態 (status、target、error)
LlmCatalog — ローカルおよびプロバイダのモデルを family ごとにまとめたもの
JobSummary — { id, kind, status, error }
DownloadProgress — パッケージ id、バイト数、ステータス

エンドポイント¶

Meta¶

Method	Path	目的
`GET`	`/meta`	アプリバージョンと有効な ML バックエンドを取得する
`GET`	`/engines`	段階ごとに登録済みのパイプライン engine を一覧する

フォント¶

Method	Path	目的
`GET`	`/fonts`	レンダリング用に system + Google Fonts を統合したカタログ
`GET`	`/google-fonts`	Google Fonts カタログを単体で取得する
`POST`	`/google-fonts/{family}/fetch`	Google Fonts の family を 1 つダウンロードしてキャッシュする
`GET`	`/google-fonts/{family}/{file}`	キャッシュ済みの TTF/WOFF ファイルを返す

Projects¶

すべてのプロジェクトは管理対象の {data.path}/projects/ 配下に置かれ、クライアントがファイルシステムパスを渡すことはありません。

Method	Path	目的
`GET`	`/projects`	管理されているプロジェクトを一覧する
`POST`	`/projects`	新しいプロジェクトを作成する (body `{ name }`)
`POST`	`/projects/import`	`.khr` アーカイブを新しいディレクトリへ展開して開く
`PUT`	`/projects/current`	`id` で管理対象プロジェクトを開く
`DELETE`	`/projects/current`	現在のセッションを閉じる
`POST`	`/projects/current/export`	現在のプロジェクトを書き出す。バイナリを返す

POST /projects/current/export は { format, pages? } を受け付け、format は khr、psd、rendered、inpainted のいずれかです。複数ファイルを生成する形式の場合、レスポンスは application/zip になります。

Pages¶

Method	Path	目的
`POST`	`/pages`	アップロードされた N 枚の画像からページを作る (multipart)
`POST`	`/pages/from-paths`	絶対パスで取り込む Tauri 専用の高速パス
`POST`	`/pages/{id}/image-layers`	アップロード画像から Custom 画像ノードを追加する
`PUT`	`/pages/{id}/masks/{role}`	生 PNG バイト列からマスクノードを upsert する
`GET`	`/pages/{id}/thumbnail`	ページサムネイルを取得する (WebP としてキャッシュ)

role は segment または brushInpaint です。POST /pages は任意の replace=true フィールドを受け付け、取り込みはファイル名を natural order で整列して行われます。

Scene と blob¶

Method	Path	目的
`GET`	`/scene.json`	Web/UI クライアント用のフルシーンスナップショット
`GET`	`/scene.bin`	Tauri クライアント用に postcard エンコードされた `Snapshot { epoch, scene }`
`GET`	`/blobs/{hash}`	Blake3 ハッシュで指定した blob の生バイト

/scene.bin は現在の epoch をレスポンスヘッダ x-koharu-epoch に含めて返します。

History (mutations)¶

シーンの変更はすべてここを通します。各レスポンスは { epoch } を返します。

Method	Path	目的
`POST`	`/history/apply`	`Op` を適用する (`Op::Batch` を含む)
`POST`	`/history/undo`	最後に適用された op を取り消す
`POST`	`/history/redo`	最後に取り消された op を再適用する

Op はノードの追加/削除/更新、ページの追加/削除、batch などのシーン遷移を表す discriminated union です。body は JSON タグ付きの variant を渡します。

Pipelines¶

Method	Path	目的
`POST`	`/pipelines`	パイプライン実行を operation として開始する

body のフィールド:

steps — 順に実行する engine id (レジストリで検証される)
pages — 任意の PageId 部分集合。省略するとプロジェクト全体が対象
region — inpainter 用の任意のバウンディングボックス (repair-brush フロー)
targetLanguage、systemPrompt、defaultFont — この実行のみの任意上書き

レスポンスは operationId を返します。進捗と完了は /events から JobStarted、JobProgress、JobWarning、JobFinished として届きます。

Operations¶

/operations は実行中および直近完了したジョブ (パイプラインとダウンロード) を統一的に扱うレジストリです。

Method	Path	目的
`GET`	`/operations`	実行中または直近の operation 一覧スナップショット
`DELETE`	`/operations/{id}`	パイプライン実行をキャンセル。ダウンロードは best-effort で除去

Downloads¶

Method	Path	目的
`GET`	`/downloads`	実行中または直近のダウンロードのスナップショット
`POST`	`/downloads`	モデルパッケージのダウンロードを開始する (`{ modelId }`)

modelId は declare_hf_model_package! で宣言されたパッケージ id (例: "model:comic-text-detector:yolo-v5") です。レスポンスはパッケージ id を再利用した { operationId } を返します。

LLM 制御¶

ロード済みモデルは /llm/current に対するシングルトンリソースとして扱われます。

Method	Path	目的
`GET`	`/llm/current`	現在の状態 (status、target、error)
`PUT`	`/llm/current`	指定 target をロードする (local または provider)
`DELETE`	`/llm/current`	モデルをアンロード/解放する
`GET`	`/llm/catalog`	ローカルおよびプロバイダのモデルを一覧する

PUT /llm/current は LlmLoadRequest を受け付けます。

provider target — { kind: "provider", providerId, modelId }
local target — { kind: "local", modelId }
任意 options { temperature, maxTokens, customSystemPrompt }

PUT /llm/current はロードタスクをキューに入れた時点で 204 を返します。実際のロード完了状態は /events の LlmLoaded で通知されます。

Config¶

Method	Path	目的
`GET`	`/config`	現在の `AppConfig` を取得する
`PATCH`	`/config`	`ConfigPatch` を適用する。永続化と broadcast を行う
`PUT`	`/config/providers/{id}/secret`	プロバイダの API キーを保存 (上書き) する
`DELETE`	`/config/providers/{id}/secret`	プロバイダに保存された API キーを削除する

AppConfig はトップレベルに data、http、pipeline、providers を持ちます。

data.path — ランタイム、モデルキャッシュ、プロジェクトに使うローカルデータディレクトリ
http { connectTimeout, readTimeout, maxRetries } — ダウンロードと provider リクエストで共有される HTTP クライアント
pipeline { detector, fontDetector, segmenter, bubbleSegmenter, ocr, translator, inpainter, renderer } — 各段階で選ばれた engine id
providers[] { id, baseUrl?, apiKey? } — 保存された API キーは生値ではなく、マスク済みプレースホルダ "[REDACTED]" で往復する

組み込みの provider id:

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

API キーはプラットフォームの credential store に保存され、config.toml には書き出されません。apiKey: "" を PATCH すると保存済みキーが削除され、"[REDACTED]" を PATCH するとそのまま維持されます。/config/providers/{id}/secret は、PATCH を介さずに 1 プロバイダのシークレットを明示的に管理するための専用ルートです。

Events stream¶

Koharu は次の URL で Server-Sent Events を公開しています。

GET /events

挙動:

新規接続 (Last-Event-ID ヘッダなし) では、最初に現在のジョブとダウンロードのレジストリを含む Snapshot イベントを送る
再接続時は seq > Last-Event-ID のバッファ済みイベントを順に再送する。要求された id が ring からスクロールアウトしている場合はサーバーが再度 Snapshot を送る
各ライブイベントは SSE の id: フィールドに seq を付けて発行される
15 秒ごとに keep-alive を送信する

現在のイベント variant:

Snapshot — 新規接続および遅延回復クライアント用の完全な状態シード
JobStarted、JobProgress、JobWarning、JobFinished — パイプライン job のライフサイクル
DownloadProgress — パッケージダウンロード進捗
ConfigChanged — PATCH /config または secret ルートで config が更新された
LlmLoaded、LlmUnloaded — LLM ライフサイクル遷移
SceneAdvanced — シーン変更により epoch が進んだときに発行される

典型的なワークフロー¶

新規プロジェクト 1 件分の通常の API 呼び出し順は次の通りです。

POST /projects — プロジェクトを作成する
POST /pages (または Tauri からは /pages/from-paths) — 画像を取り込む
PUT /llm/current — 翻訳用モデルをロードする (local または provider)
POST /pipelines — detect → ocr → translate → inpaint → render を開始する
JobFinished まで GET /events を tail する
format = "rendered" または "psd" を指定して POST /projects/current/export

より細かく制御したい場合は、フルパイプラインを実行する代わりに、明示的な Op ペイロードで POST /history/apply を呼びます。

HTTP エンドポイントを順に叩く代わりに、エージェント向けのアクセスが欲しい場合は MCP ツールリファレンスを参照してください。