プログラム用ツール

公開機能一覧は 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 秒、同時 1 件。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 の画像 URL を使います。

認証: ローカルサービスの 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`	実行の完了を待つか結果を削除。