docs/ja-JP/reference/http-api.md

---
title: HTTP API リファレンス
---

# HTTP API リファレンス

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

```text
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 を公開しています。

```text
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 呼び出し順は次の通りです。

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

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

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