程序化工具

公开发现接口位于 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`	等待任务完成或删除旧结果。