REST API 參考

API 資訊

屬性	值
版本	v1.0
Base URL	`http://localhost:65530/api`
Content-Type	`application/json`
認證	無需認證

資料模型

Task

地圖畫建造任務物件

欄位	類型	必填	描述
`Group`	string	✓	群組名稱
`Type`	string	✓	任務類型，固定為 "mapArt"
`ID`	string	✓	任務唯一識別碼
`Status`	enum	✓	任務狀態：`init`, `building`, `done`, `error`, `pause`
`Record`	TaskRecord		建造記錄
`BlueprintPath`	string	✓	地圖畫檔案路徑
`OffsetX`	number	✓	X 軸偏移量
`OffsetY`	number	✓	Y 軸偏移量
`OffsetZ`	number	✓	Z 軸偏移量
`MaterialServer`	number	✓	材料伺服器編號
`BuildingServer`	number	✓	建造伺服器編號
`MaterialWarpPoint`	string		材料傳送點名稱
`BuildingWarpPoint`	string		建造傳送點名稱
`IsDestroy`	boolean		是否為破壞模式
`InitialTime`	string		初始化時間 (ISO 8601)

TaskRecord

任務執行記錄

欄位	類型	描述
`TotalBlocks`	number	總方塊數
`RemainBlocks`	number	剩餘方塊數
`StartTime`	string	開始時間 (ISO 8601)
`FinishTime`	string	完成時間 (ISO 8601)
`Finish`	boolean	是否完成
`BuildScopes`	BuildScope[]	建造時間範圍
`StopTimes`	number	停止次數
`TakeMaterialTimes`	number	取材次數
`PlaceBlockTimes`	number	放置方塊次數
`TakeMaterialTime`	number	取材耗時 (納秒)
`PreviewImage`	string[]	預覽圖片 (Base64)
`Width`	number	寬度
`Height`	number	高度
`ErrorMessage`	string	錯誤訊息
`Materials`	any[]	材料清單

BuildScope

建造時間範圍

欄位	類型	必填	描述
`StartTime`	string	✓	開始時間 (ISO 8601)
`EndTime`	string	✓	結束時間 (ISO 8601)

Map

地圖物件

欄位	類型	必填	描述
`uuid`	string	✓	地圖唯一識別碼
`id`	number	✓	地圖 ID 編號
`rename`	boolean		是否啟用重新命名
`name`	string		當前地圖名稱
`skip`	boolean		是否跳過此地圖
`origin_name`	string		原始地圖名稱
`copy`	boolean		是否複製此地圖
`copy_count`	number		複製數量

ItemData

物品資料

欄位	類型	必填	描述
`id`	number	✓	物品 ID 編號
`translate_name`	string	✓	翻譯後名稱
`name`	string	✓	英文原名稱
`stack_size`	number	✓	堆疊上限

EULA

最終用戶授權協議物件

欄位	類型	必填	描述
`id`	number	✓	EULA 唯一識別碼
`version`	string	✓	EULA 版本號
`title`	string	✓	EULA 標題
`content`	string	✓	EULA 完整內容
`is_active`	number	✓	是否為啟用狀態 (0 或 1)
`created_at`	string	✓	建立時間 (ISO 8601)
`updated_at`	string	✓	更新時間 (ISO 8601)

API 端點

系統管理

`GET /test`

檢查 Bot 客戶端連線狀態

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 已連接 `"not ok"` - 未連接

`GET /user/name`

取得當前 Bot 客戶端名稱

回應

狀態碼	內容類型	描述
200	`text/plain`	Bot 客戶端名稱

`POST /exit`

安全退出 Nullbot Mapart 程式

回應

狀態碼	描述
200	退出流程已觸發

`POST /profile`

執行系統效能分析

回應

狀態碼	內容類型	描述
200	`text/plain`	`"Profile finished"` - 分析完成
201	`text/plain`	`"Profile is already running"` - 已在執行中
500	`text/plain`	分析失敗錯誤訊息

`GET /auth`

取得 GMM 驗證資訊

回應

狀態碼	內容類型	Schema
200	`application/json`	`{"Code": string, "RedirectUri": string}`

`GET /tunnel-auth`

隧道服務驗證端點

EULA 管理

`GET /eula`

取得 EULA 內容

回應

狀態碼	內容類型	Schema
200	`application/json`	EULA

`GET /eula/status`

取得 EULA 接受狀態

回應

狀態碼	內容類型	Schema
200	`application/json`	`{"status": string}`

狀態值:

"accepted" - 已接受
"denied" - 已拒絕
"idle" - 未回應

`POST /eula/accept`

接受 EULA

請求體

內容類型	Schema
`application/json`	`{"accepted": boolean, "reading_time": number, "response_type": string}`

回應

狀態碼	內容類型	描述
200	`application/json`	`{"status": "EULA accepted"}` - EULA 接受成功
400	`application/json`	`{"error": "invalid request"}` - 請求格式錯誤
403	`application/json`	`{"error": "EULA not accepted"}` - EULA 未被接受

配置管理

`GET /config/{service}`

取得服務配置

路徑參數

參數	類型	必填	描述
`service`	string	✓	服務名稱

回應

狀態碼	內容類型	描述
200	`application/json`	服務配置物件
404		服務不存在

`POST /config/{service}`

更新服務配置

路徑參數

參數	類型	必填	描述
`service`	string	✓	服務名稱

請求體

內容類型	Schema
`application/json`	配置物件

回應

狀態碼	描述
200	配置更新成功
400	請求參數錯誤
404	服務不存在

地圖畫建造

`GET /mapart/tasks`

取得所有建造任務

回應

狀態碼	內容類型	Schema
200	`application/json`	Task[]

`POST /mapart/tasks`

建立建造任務

請求體

內容類型	Schema
`application/json`	Task \| Task[]

回應

狀態碼	內容類型	描述
200	`text/plain`	任務 ID (多任務以逗號分隔)
400	`text/plain`	參數錯誤或座標未對齊
500	`text/plain`	伺服器內部錯誤

`GET /mapart/tasks/{id}`

取得特定任務

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

回應

狀態碼	內容類型	Schema
200	`application/json`	Task
404		任務不存在

`PUT /mapart/tasks/{id}`

更新任務

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

請求體

內容類型	Schema
`application/json`	Task

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 更新成功
400	`text/plain`	參數錯誤或任務未初始化
404		任務不存在
500	`text/plain`	伺服器內部錯誤

`DELETE /mapart/tasks/{id}`

刪除任務

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 刪除成功
404		任務不存在
500	`text/plain`	伺服器內部錯誤

`DELETE /mapart/tasks/batch`

批次刪除任務

請求體

內容類型	Schema
`application/json`	string[]

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 全部刪除成功
207	`application/json`	部分成功的詳細狀態
400	`text/plain`	請求參數錯誤
404		所有任務都不存在

`POST /mapart/build/{id}`

開始建造

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 建造開始成功
400	`text/plain`	任務已在執行中
404		任務不存在
500	`text/plain`	伺服器內部錯誤

`POST /mapart/rebuild/{id}`

重新建造

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 重新建造設定成功
404		歷史任務不存在
500	`text/plain`	伺服器內部錯誤

`POST /mapart/stop`

停止建造

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 停止成功
400	`text/plain`	無進行中的任務

`POST /mapart/order`

任務排序

請求體

內容類型	Schema
`application/json`	`{"type": string, "source": number, "destination": number}`

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 排序成功
400	`text/plain`	參數錯誤或類型無效
500	`text/plain`	伺服器內部錯誤

`GET /mapart/task/autoBuild`

取得自動建造狀態

回應

狀態碼	內容類型	Schema
200	`application/json`	boolean

`POST /mapart/task/autoBuild`

設定自動建造

查詢參數

參數	類型	必填	描述
`auto`	string	✓	`"true"` 或 `"false"`

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	缺少 auto 參數

`GET /mapart/history`

取得建造歷史

回應

狀態碼	內容類型	Schema
200	`application/json`	Task[]

`GET /preview/{id}`

取得任務預覽圖片

路徑參數

參數	類型	必填	描述
`id`	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	`image/png`	預覽圖片
404		任務不存在

`GET /render`

渲染當前建造任務

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 渲染成功
400	`text/plain`	無進行中的任務
500	`text/plain`	渲染或檔案儲存錯誤

後處理操作

`POST /postProcessing/scan`

掃描地圖

請求體

內容類型	Schema
`application/json`	`{"Start": string, "Width": number, "Height": number, "Order": string, "Template": string, "CopyAmount": number}`

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 掃描任務開始
400	`text/plain`	參數錯誤或任務鎖定

`GET /postProcessing/maps`

取得地圖列表

回應

狀態碼	內容類型	Schema
200	`application/json`	Map[]

`GET /postProcessing/map/{id}`

取得特定地圖資訊

路徑參數

參數	類型	必填	描述
`id`	string	✓	地圖 ID

回應

狀態碼	內容類型	Schema
200	`application/json`	`{"MapID": number, "Locked": boolean}`
400	`text/plain`	地圖 ID 格式錯誤
404		地圖不存在

`GET /postProcessing/map/{id}/image`

取得地圖圖片

路徑參數

參數	類型	必填	描述
`id`	string	✓	地圖 ID

回應

狀態碼	內容類型	描述
200	`image/png`	128x128 PNG 圖片
400	`text/plain`	地圖 ID 格式錯誤
404		地圖不存在
500	`text/plain`	圖片編碼錯誤

`POST /postProcessing/map/clear`

清除地圖快取

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 清除成功
400	`text/plain`	任務已鎖定或清除失敗

`POST /postProcessing`

設定複製參數

請求體

內容類型	Schema
`application/json`	`{"Start": string, "Width": number, "Height": number, "Order": string, "Template": string, "CopyAmount": number}`

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/size`

設定複製尺寸

查詢參數

參數	類型	必填	描述
`width`	number	✓	寬度
`height`	number	✓	高度

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/copyAmount`

設定複製數量

查詢參數

參數	類型	必填	描述
`amount`	number	✓	複製數量

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/copy`

開始複製

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 複製任務開始
400	`text/plain`	任務已鎖定

`POST /postProcessing/copy/{uuid}`

設定特定地圖複製

路徑參數

參數	類型	必填	描述
`uuid`	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
`copy`	boolean	✓	是否複製

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/copyCount/{uuid}`

設定複製計數

路徑參數

參數	類型	必填	描述
`uuid`	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
`count`	number	✓	複製數量

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/setRename`

設定重新命名參數

請求體

內容類型	Schema
`application/json`	`[{"uuid": string, "rename": boolean}]`

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	請求體錯誤或任務鎖定

`POST /postProcessing/rename`

開始重新命名

查詢參數

參數	類型	必填	描述
`mode`	string		重新命名模式 (預設: loose)

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 重新命名任務開始
400	`text/plain`	任務已鎖定

`POST /postProcessing/template`

設定命名範本

查詢參數

參數	類型	必填	描述
`template`	string	✓	命名範本字串

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`GET /postProcessing/template/docs`

取得範本文檔

回應

狀態碼	內容類型	Schema
200	`application/json`	`[{"Type": string, "Name": string, "Description": string, "Example": string}]`

`POST /postProcessing/name/{uuid}`

設定地圖名稱

路徑參數

參數	類型	必填	描述
`uuid`	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
`name`	string	✓	新的地圖名稱

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤、名稱太長或任務鎖定

`POST /postProcessing/order`

設定排序

查詢參數

參數	類型	必填	描述
`order`	string	✓	排序方式

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/skip/{uuid}`

跳過地圖

路徑參數

參數	類型	必填	描述
`uuid`	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
`skip`	boolean	✓	是否跳過

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 設定成功
400	`text/plain`	參數錯誤或任務鎖定

`POST /postProcessing/stop`

停止後處理

回應

狀態碼	內容類型	描述
200	`text/plain`	`"ok"` - 停止成功

背景圖片管理

`GET /background`

取得背景圖片

回應

狀態碼	內容類型	描述
200	原始 MIME 類型	當前背景圖片
404		未設定背景圖片
500	`text/plain`	伺服器錯誤

回應標頭

ETag: 快取標識

`GET /background/list`

取得背景列表

回應

狀態碼	內容類型	Schema
200	`application/json`	string[]

`POST /background/upload`

上傳背景圖片

請求體

內容類型	Schema
`multipart/form-data`	`background`: File

回應

狀態碼	內容類型	描述
200	`text/plain`	圖片雜湊值
400	`text/plain`	未找到檔案
415	`text/plain`	檔案不是圖片格式
500	`text/plain`	伺服器錯誤

`POST /background/set`

設定背景

查詢參數

參數	類型	必填	描述
`hash`	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	`text/plain`	`"OK"` - 設定成功
404		背景圖片不存在
500	`text/plain`	伺服器錯誤

`POST /background/set/{hash}`

設定特定背景

路徑參數

參數	類型	必填	描述
`hash`	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	`text/plain`	`"OK"` - 設定成功
404		背景圖片不存在
500	`text/plain`	伺服器錯誤

`GET /background/hash`

取得背景雜湊

回應

狀態碼	內容類型	描述
200	`text/plain`	當前背景雜湊值
404		未設定背景

`GET /background/{hash}`

取得背景圖片

路徑參數

參數	類型	必填	描述
`hash`	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	原始 MIME 類型	圖片檔案
404		背景圖片不存在
500	`text/plain`	伺服器錯誤

回應標頭

Cache-Control: max-age=31536000

`GET /background/thumbnail/{hash}`

取得背景縮圖

路徑參數

參數	類型	必填	描述
`hash`	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	`image/jpg`	JPG 縮圖
404		背景圖片不存在
500	`text/plain`	伺服器錯誤

回應標頭

Cache-Control: max-age=31536000

`GET /background/position`

取得背景位置

回應

狀態碼	內容類型	Schema
200	`application/json`	number
404		未設定背景或背景不存在
500	`text/plain`	伺服器錯誤

`POST /background/position`

設定背景位置

查詢參數

參數	類型	必填	描述
`position`	number	✓	背景位置數值

回應

狀態碼	內容類型	描述
200	`text/plain`	`"OK"` - 設定成功
404		未設定背景或背景不存在
500	`text/plain`	伺服器錯誤

資料查詢

`GET /data/items`

取得物品列表

回應

狀態碼	內容類型	Schema
200	`application/json`	ItemData[]

`GET /data/items/maxDamage`

取得物品最大耐久度

回應

狀態碼	內容類型	Schema
200	`application/json`	`{[itemId: string]: number}`

`GET /assets/items`

取得物品圖示

查詢參數

參數	類型	必填	描述
`id`	number	✓	物品 ID

回應

狀態碼	內容類型	描述
200	`image/png`	物品圖示 PNG
404		物品 ID 不存在或圖示檔案不存在
500	`text/plain`	檔案讀取錯誤

回應標頭

Cache-Control: max-age=86400

`GET /header`

頭像渲染

查詢參數

參數	類型	必填	描述
`key`	string	*	玩家名稱 (與 url 二擇一)
`url`	string	*	皮膚貼圖網址 (與 key 二擇一)
`size`	number		圖片尺寸 (預設: 512)
`overlay`	boolean		是否渲染第二層皮膚 (預設: true)
`projection`	string		投影方式: `frontal` 或 `isometric` (預設: isometric)

回應

狀態碼	內容類型	描述
200	`image/png`	渲染後的頭像 PNG
304		未修改 (基於 ETag)
400	`text/plain`	參數錯誤、皮膚獲取失敗或非法貼圖服務
5000	`text/plain`	渲染錯誤
5001	`text/plain`	圖片編碼錯誤

回應標頭

ETag: 快取標識
Cache-Control: max-age=86400

狀態碼

狀態碼	說明
200	請求成功
201	已創建
207	多狀態回應 (部分成功)
304	未修改 (快取有效)
400	請求參數錯誤
401	未授權
404	資源不存在
415	不支援的媒體類型
500	伺服器內部錯誤
5000	自訂錯誤：渲染失敗
5001	自訂錯誤：編碼失敗

REST API 參考 ​

API 資訊 ​

資料模型 ​

Task ​

TaskRecord ​

BuildScope ​

Map ​

ItemData ​

EULA ​

API 端點 ​

系統管理 ​

GET /test ​

GET /user/name ​

POST /exit ​

POST /profile ​

GET /auth ​

GET /tunnel-auth ​

EULA 管理 ​

GET /eula ​

GET /eula/status ​

POST /eula/accept ​

配置管理 ​

GET /config/{service} ​

POST /config/{service} ​

地圖畫建造 ​

GET /mapart/tasks ​

POST /mapart/tasks ​

GET /mapart/tasks/{id} ​

PUT /mapart/tasks/{id} ​

DELETE /mapart/tasks/{id} ​

DELETE /mapart/tasks/batch ​

POST /mapart/build/{id} ​

POST /mapart/rebuild/{id} ​

POST /mapart/stop ​

POST /mapart/order ​

GET /mapart/task/autoBuild ​

POST /mapart/task/autoBuild ​

GET /mapart/history ​

GET /preview/{id} ​

GET /render ​

後處理操作 ​

POST /postProcessing/scan ​

GET /postProcessing/maps ​

GET /postProcessing/map/{id} ​

GET /postProcessing/map/{id}/image ​

POST /postProcessing/map/clear ​

POST /postProcessing ​

POST /postProcessing/size ​

POST /postProcessing/copyAmount ​

POST /postProcessing/copy ​

POST /postProcessing/copy/{uuid} ​

POST /postProcessing/copyCount/{uuid} ​

POST /postProcessing/setRename ​

POST /postProcessing/rename ​

POST /postProcessing/template ​

GET /postProcessing/template/docs ​

POST /postProcessing/name/{uuid} ​

POST /postProcessing/order ​

POST /postProcessing/skip/{uuid} ​

POST /postProcessing/stop ​

背景圖片管理 ​

GET /background ​

GET /background/list ​

POST /background/upload ​

POST /background/set ​

POST /background/set/{hash} ​

GET /background/hash ​

GET /background/{hash} ​

GET /background/thumbnail/{hash} ​

GET /background/position ​

POST /background/position ​

資料查詢 ​

GET /data/items ​

GET /data/items/maxDamage ​

GET /assets/items ​

GET /header ​

狀態碼 ​

REST API 參考

API 資訊

資料模型

Task

TaskRecord

BuildScope

Map

ItemData

EULA

API 端點

系統管理

`GET /test`

`GET /user/name`

`POST /exit`

`POST /profile`

`GET /auth`

`GET /tunnel-auth`

EULA 管理

`GET /eula`

`GET /eula/status`

`POST /eula/accept`

配置管理

`GET /config/{service}`

`POST /config/{service}`

地圖畫建造

`GET /mapart/tasks`

`POST /mapart/tasks`

`GET /mapart/tasks/{id}`

`PUT /mapart/tasks/{id}`

`DELETE /mapart/tasks/{id}`

`DELETE /mapart/tasks/batch`

`POST /mapart/build/{id}`

`POST /mapart/rebuild/{id}`

`POST /mapart/stop`

`POST /mapart/order`

`GET /mapart/task/autoBuild`

`POST /mapart/task/autoBuild`

`GET /mapart/history`

`GET /preview/{id}`

`GET /render`

後處理操作

`POST /postProcessing/scan`

`GET /postProcessing/maps`

`GET /postProcessing/map/{id}`

`GET /postProcessing/map/{id}/image`

`POST /postProcessing/map/clear`

`POST /postProcessing`

`POST /postProcessing/size`

`POST /postProcessing/copyAmount`

`POST /postProcessing/copy`

`POST /postProcessing/copy/{uuid}`

`POST /postProcessing/copyCount/{uuid}`

`POST /postProcessing/setRename`

`POST /postProcessing/rename`

`POST /postProcessing/template`

`GET /postProcessing/template/docs`

`POST /postProcessing/name/{uuid}`

`POST /postProcessing/order`

`POST /postProcessing/skip/{uuid}`

`POST /postProcessing/stop`

背景圖片管理

`GET /background`

`GET /background/list`

`POST /background/upload`

`POST /background/set`

`POST /background/set/{hash}`

`GET /background/hash`

`GET /background/{hash}`

`GET /background/thumbnail/{hash}`

`GET /background/position`

`POST /background/position`

資料查詢

`GET /data/items`

`GET /data/items/maxDamage`

`GET /assets/items`

`GET /header`

狀態碼