프로그램 도구

공개 기능 확인은 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 작업이 반환한 이미지 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`	실행 완료를 기다리거나 결과를 삭제하세요.