遠端圖片處理器

本規範定義 Mankai 遠端圖片處理器使用的 HTTP API。使用者在設定 → 圖片處理中新增伺服器基礎網址。Mankai 讀取處理器中繼資料、顯示伺服器定義的設定欄位，並在處理器啟用時將閱讀器中的每張圖片發送到伺服器。

應用程式中的設定和使用方法請參閱圖片處理。

端點

方法	路徑	認證	用途
`GET`	`/`	無需	回傳處理器中繼資料和設定
`POST`	`/process`	可選	處理一張圖片
`POST`	`/auth/login`	無需	啟用認證時登入
`POST`	`/auth/refresh`	無需	更新存取權杖

使用者輸入的網址是基礎網址。例如輸入 https://images.example.com/mankai 後，處理端點為 https://images.example.com/mankai/process。

處理器資訊

`GET /`

回應 — 200 OK

interface ImageProcessorInfo {
  id: string // Stable server/processor identifier
  name?: string
  version?: string
  description?: string
  authors?: string[] // Default: []
  repository?: string
  authenticationEnabled?: boolean // Default: false
  configs?: Config[] // Default: []
}

type ConfigType =
  'text' | 'password' | 'number' | 'slider' | 'boolean' | 'select' | 'color'

interface Config {
  key: string // Unique within this processor
  name: string // User-facing label or localization key
  description?: string
  type: ConfigType
  defaultValue: string | number | boolean
  options?: string[] // Used by "select"
  min?: number // Used by "slider"
  max?: number // Used by "slider"
  step?: number // Used by "slider"
  supportsOpacity?: boolean // Used by "color", defaults to false
}

範例：

{
  "id": "com.example.manga-denoise",
  "name": "Manga Denoise",
  "version": "1.0.0",
  "description": "Removes scan noise while preserving line art.",
  "authors": ["Example Lab"],
  "repository": "https://example.com/manga-denoise",
  "authenticationEnabled": false,
  "configs": [
    {
      "key": "strength",
      "name": "Strength",
      "description": "Higher values remove more noise.",
      "type": "slider",
      "defaultValue": 0.5,
      "min": 0,
      "max": 1,
      "step": 0.1
    },
    {
      "key": "preserveText",
      "name": "Preserve text",
      "type": "boolean",
      "defaultValue": true
    }
  ]
}

圖片處理

`POST /process`

請求使用 multipart/form-data，以保留圖片的二進位形式。必須包含以下三個指定名稱的部分。

部分	內容類型	值
`image`	`image/png`	目前處理流程中的圖片，以 PNG 檔案提供
`configs`	`application/json`	伺服器定義的所有設定項目的目前值
`context`	`application/json`	閱讀器顯示尺寸，以邏輯點為單位

configs 使用與 JavaScript 外掛模組設定 API 相同的鍵值結構。

interface ConfigValue {
  key: string
  value: string | number | boolean
}

type ConfigValues = ConfigValue[]

configs 部分的範例：

[
  { "key": "strength", "value": 0.8 },
  { "key": "preserveText", "value": true }
]

context 部分採用以下結構。

interface ProcessContext {
  pointSize: {
    width: number
    height: number
  }
}

伺服器必須直接回傳處理後的圖片，並使用 2xx 狀態碼和 image/* 類型的 Content-Type。允許 PNG、JPEG、WebP、HEIF 以及用戶端平台支援的其他圖片格式。回應會傳遞給下一個已設定的圖片處理器，因此伺服器應保留足夠的解析度和畫質。

認證（可選）

將 authenticationEnabled 設為 true，即可讓 POST /process 要求 JWT Bearer 認證。Mankai 隨後顯示使用者名稱和密碼欄位，並使用與 HTTP 外掛模組相同的權杖流程。

`POST /auth/login`

請求內文

{
  "username": "user",
  "password": "secret"
}

回應 — 200 OK

{
  "accessToken": "short-lived JWT",
  "refreshToken": "long-lived refresh token"
}

`POST /auth/refresh`

請求內文

{
  "refreshToken": "long-lived refresh token"
}

回應 — 200 OK

{
  "accessToken": "new short-lived JWT"
}