程式化工具

公開探索介面位於 haneoka.org，任務介面執行於本機服務。啟動與完整範例見本機計算指南。

探索

探索 API 能力

GETHEAD /api/v1

機器可讀的入口、請求契約與工具模組。

驗證: 無需驗證，可匿名公開讀取。
快取: public, max-age=300

請求範例

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1"

const response = await fetch("https://haneoka.org/api/v1");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 200 OK

{}

為節省篇幅已截斷，實際回應包含更多項目。

完整 OpenAPI

GETHEAD /api/v1/openapi.json

機器可讀的入口、請求契約與工具模組。

驗證: 無需驗證，可匿名公開讀取。
快取: public, max-age=300

請求範例

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1/openapi.json"

const response = await fetch("https://haneoka.org/api/v1/openapi.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 200 OK

{}

為節省篇幅已截斷，實際回應包含更多項目。

裝置計算模組

GETHEAD /api/v1/tools

機器可讀的入口、請求契約與工具模組。

驗證: 無需驗證，可匿名公開讀取。
快取: public, max-age=300

請求範例

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1/tools"

const response = await fetch("https://haneoka.org/api/v1/tools");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 200 OK

{}

為節省篇幅已截斷，實際回應包含更多項目。

本機計算

本機服務能力

GET /v1

回傳操作、並行數與結果保留時間。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

請求範例

cURL
JavaScript

curl -sS "http://127.0.0.1:8765/v1" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 200 OK

{
  "operations": [
    "search",
    "evaluate",
    "growth",
    "timeline",
    "chart-image"
  ],
  "concurrency": 1,
  "resultTtlSeconds": 600
}

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

提交本機計算

POST /v1/jobs

回傳 202 與查詢位置 Location。請求本文 2 MiB、排隊 8 個、同時執行 1 個、上限 5 分鐘。庫存留在本機。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

請求主體 application/json

名稱	型別	說明
`operation`必填	string	search、evaluate、growth、timeline、chart-image 或 resource-image。
`request`選填	object	計算任務必填，使用 tools/schema.json 中的對應型別。

請求範例

cURL
JavaScript

curl -sS -X POST "http://127.0.0.1:8765/v1/jobs" \
  -H "Authorization: Bearer ${localToken}" \
  -H "Content-Type: application/json" \
  --data '{"operation":"chart-image","server":"intl","songId":"100001","difficulty":"expert","locale":"en","height":720}'

const response = await fetch("http://127.0.0.1:8765/v1/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${localToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "operation": "chart-image",
    "server": "intl",
    "songId": "100001",
    "difficulty": "expert",
    "locale": "en",
    "height": 720
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 202 Accepted
Location: /v1/jobs/00000000-0000-4000-8000-000000000001

{
  "id": "00000000-0000-4000-8000-000000000001",
  "operation": "chart-image",
  "state": "queued"
}

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

讀取任務進度與結果

GET /v1/jobs/{id}

狀態：queued、running、completed、failed。完成後保留 10 分鐘，讀取 result、identity 與可選 image URL。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

參數

名稱	位置	型別	說明
`id`必填	路徑	uuid	提交任務回傳的 ID。

請求範例

cURL
JavaScript

curl -sS "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();

回應範例

HTTP/2 200 OK

{
  "id": "00000000-0000-4000-8000-000000000001",
  "operation": "search",
  "state": "completed",
  "createdAt": 1793030400000,
  "expiresAt": 1793031000000,
  "result": {
    "overall": [],
    "results": [],
    "stopReason": "complete"
  }
}

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

取消並刪除任務

DELETE /v1/jobs/{id}

終止計算環境並刪除結果，後續讀取回傳 404。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

參數

名稱	位置	型別	說明
`id`必填	路徑	uuid	提交任務回傳的 ID。

請求範例

cURL
JavaScript

curl -sS -X DELETE "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);

回應範例

HTTP/2 204 No Content

沒有回應主體。

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

下載完成的圖片

GET /v1/jobs/{id}/image.png

使用已完成的 chart-image 任務與同一本機 Bearer 權杖，回傳 PNG；未就緒為 409。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

參數

名稱	位置	型別	說明
`id`必填	路徑	uuid	提交任務回傳的 ID。

請求範例

cURL
JavaScript

curl -sS -o output.bin "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/image.png" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/image.png", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

回應範例

HTTP/2 200 OK

二進位內容（不顯示）。

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

本機繪製資源圖片

POST /v1/resource-image

與資源圖片 API 使用相同請求。JSON 8 MiB、輸出 16 MiB、50 秒，每次執行一個任務。kind、data 與檢視器狀態見圖片匯出指南。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

請求主體 application/json

名稱	型別	說明
`kind`必填	string	team、gacha、gacha-history、stamp、chart、live2d 或 spine。
`data`必填	object	網頁匯出模型，見 /reference/images/。

請求範例

cURL
JavaScript

curl -sS -o output.bin -X POST "http://127.0.0.1:8765/v1/resource-image" \
  -H "Authorization: Bearer ${localToken}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @resource-image.json

const response = await fetch("http://127.0.0.1:8765/v1/resource-image", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${localToken}`,
    "Content-Type": "application/octet-stream",
  },
  body: file,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

回應範例

HTTP/2 200 OK

二進位內容（不顯示）。

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。

下載報表圖片 ZIP

GET /v1/jobs/{id}/images.zip

使用已完成 resource-image 封存任務回傳的圖片位址。

驗證: 本機服務 Bearer 權杖，讀取啟動時提供的私人請求標頭檔。
快取: no-store

參數

名稱	位置	型別	說明
`id`必填	路徑	uuid	提交任務回傳的 ID。

請求範例

cURL
JavaScript

curl -sS -o output.bin "http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/images.zip" \
  -H "Authorization: Bearer ${localToken}"

const response = await fetch("http://127.0.0.1:8765/v1/jobs/00000000-0000-4000-8000-000000000001/images.zip", {
  headers: {
    Authorization: `Bearer ${localToken}`,
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

回應範例

HTTP/2 200 OK

二進位內容（不顯示）。

錯誤

狀態碼	代碼	意義
`400`	`invalid_request`	路徑或查詢中的 ID 格式錯誤。
`401`	`unauthorized`	傳入本機 Bearer 權杖。
`403`	`origin_not_allowed`	從本機用戶端或指令碼呼叫。
`404`	`not_found`	未知的地區或紀錄。
`404`	`job_not_found`	任務已過期或被刪除。
`409`	`image_not_ready`	等待圖片任務完成。
`413`	`body_too_large`	請求本文超過 2 MiB。
`429`	`rate_limit_exceeded`	該鍵的請求過多；如有 `Retry-After` 請遵守。
`429`	`queue_full`	等待任務完成或刪除舊結果。