채보 이미지

사이트 다운로드와 같은 음표 아틀라스·슬라이드·재킷·아이콘·글꼴·레이아웃을 사용합니다. release를 고정하면 입력을 재현할 수 있습니다. 브라우저 서비스에서 PNG를 생성하고 SVG에는 같은 PNG를 넣습니다. 전체 채보를 열로 배치합니다. 기기 내보내기는 로컬 계산을 확인하세요. ETag에는 release·이미지 옵션·내용 해시가 포함됩니다.

채보 렌더링

채보 이미지 렌더링

GETHEAD /api/v1/songs/{songId}/charts/{difficulty}/image.{format}

?server=(기본 intl)로 서버를 고르는 단축형입니다. 아래 범위형과 똑같이 동작합니다.

인증: 필요 없음. 누구나 익명으로 읽을 수 있습니다.
캐시: public, max-age=300, must-revalidate

매개변수

이름	위치	타입	설명
`release`선택	쿼리	string	변경되지 않는 릴리스로 고정합니다. `r-` 뒤에 소문자 16진수 20자리. 생략하면 현재 릴리스를 읽습니다. 서버와 릴리스 참고.
`timeZone`선택	쿼리	string	공개 시각의 IANA 시간대. 브라우저 다운로드와 맞추려면 같은 시간대를 지정하세요. 기본값: `Asia/Tokyo`
`songId`필수	경로	string	`songs` 리소스의 곡 ID(`musicId`).
`difficulty`필수	경로	string	`easy`, `normal`, `hard`, `expert`, `special`, `master` 중 곡의 `difficulty[].difficultyName`에 있는 값.
`format`필수	경로	string	원본 소재 PNG 또는 같은 PNG를 포함한 SVG.
`locale`선택	쿼리	string	제목과 밴드 이름의 언어: `ja`, `en`, `zh-TW`, `zh-CN`, `ko`. 기본값은 `Accept-Language` 협상.
`height`선택	쿼리	integer	채보 열의 높이(px, 360~1440). 헤더가 더해져 최종 이미지는 더 높습니다. `X-Haneoka-Image-Width`/`-Height`를 확인하세요. 기본값: `720`
`download`선택	쿼리	string	`1`은 `Content-Disposition: attachment`, `0`은 `inline`이라 브라우저 탭이나 `<img>`에서 보여 줄 수 있습니다. 기본값: `1`
`server`선택	쿼리	string	리소스 서버 슬러그. 기본값은 `intl`이며 한 번만 보낼 수 있습니다. 기본값: `intl`

요청 예시

cURL
JavaScript

curl -sS "https://haneoka.org/api/v1/songs/100001/charts/expert/image.svg?locale=en&download=0"

const response = await fetch("https://haneoka.org/api/v1/songs/100001/charts/expert/image.svg?locale=en&download=0");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const text = await response.text();

응답 예시

HTTP/2 200 OK
Content-Type: image/svg+xml; charset=utf-8
Content-Disposition: inline; filename="Haneoka-intl-100001-expert-en.svg"
Content-Language: en
Cache-Control: public, max-age=300, must-revalidate
ETag: "intl:r-8da1a1f914879ac54d8a:100001:en:expert:chart-overview-native-v3:452c560d…"
X-Haneoka-Chart-Renderer: chart-overview-native-v3
X-Haneoka-Image-Width: 5360
X-Haneoka-Image-Height: 2144
X-Haneoka-Release-Id: r-8da1a1f914879ac54d8a
X-Haneoka-Server: intl

<svg xmlns="http://www.w3.org/2000/svg" lang="en" width="5360" height="2144" viewBox="0 0 5360 2144">
<image width="5360" height="2144" href="data:image/png;base64,…"/>
</svg>

길이 때문에 일부를 생략했습니다. 실제 응답에는 더 많은 항목이 있습니다.

오류

상태	코드	의미
`304`	—	`If-None-Match` 또는 `If-Modified-Since`가 일치했습니다. 캐시된 사본을 재사용하세요.
`400`	`invalid_time_zone`	유효한 IANA 시간대를 사용하세요.
`400`	`invalid_height`	`height`는 360~1440 사이의 정수여야 합니다.
`400`	`invalid_download`	`download`는 `0` 또는 `1`이어야 합니다.
`400`	`invalid_locale`	`locale`이 `ja`, `en`, `zh-TW`, `zh-CN`, `ko` 중 하나가 아닙니다.
`400`	`invalid_server`	`server`가 여러 번 전송되었거나 경로와 일치하지 않습니다.
`400`	`invalid_release`	`release`가 `r-` 뒤에 16진수 20자리가 아니거나 허용하지 않는 경로에 전송되었습니다.
`400`	`body_not_allowed`	채보 이미지 요청에는 본문을 넣을 수 없습니다.
`404`	`server_not_found`	서버 슬러그가 활성 리소스 서버가 아닙니다.
`404`	`song_not_found`	곡이 현재 릴리스에 없습니다.
`404`	`difficulty_not_found`	이 난이도의 채보가 없습니다.
`404`	`chart_not_found`	릴리스에 채보 파일이 없습니다.
`404`	`release_not_found`	요청한 릴리스를 이 서버에서 사용할 수 없습니다.
`406`	`format_not_supported`	확장자는 `svg` 또는 `png`여야 합니다.
`413`	`chart_too_large`	원본 채보가 렌더링 한도 2MiB를 초과합니다.
`413`	`chart_render_budget`	렌더링 결과가 픽셀 또는 SVG 한도를 초과합니다.
`502`	`chart_invalid`	릴리스의 채보를 해석하지 못했습니다.
`502`	`chart_path_invalid`	카탈로그의 채보 경로가 잘못되었습니다.
`502`	`png_invalid`	래스터라이저가 잘못된 PNG를 반환했습니다.
`502`	`chart_image_failed`	렌더링이 예기치 않게 실패했습니다.
`503`	`release_unavailable`	이 서버에는 아직 현재 릴리스가 게시되지 않았습니다.
`503`	`native_renderer_unavailable`	원본 이미지 서비스를 사용할 수 없습니다. 기기의 renderChartImage 모듈을 사용할 수 있습니다.

서버를 지정해 채보 이미지 렌더링

GETHEAD /api/v1/servers/{server}/songs/{songId}/charts/{difficulty}/image.{format}

범위형입니다. server 쿼리를 보내면 경로 값과 같아야 합니다. 요청에 본문을 넣을 수 없습니다.

인증: 필요 없음. 누구나 익명으로 읽을 수 있습니다.
캐시: public, max-age=300, must-revalidate

매개변수

이름	위치	타입	설명
`server`필수	경로	string	`GET /api/v1/releases`가 반환하는 리소스 서버 슬러그(예: `intl`, `jp`).
`release`선택	쿼리	string	변경되지 않는 릴리스로 고정합니다. `r-` 뒤에 소문자 16진수 20자리. 생략하면 현재 릴리스를 읽습니다. 서버와 릴리스 참고.
`timeZone`선택	쿼리	string	공개 시각의 IANA 시간대. 브라우저 다운로드와 맞추려면 같은 시간대를 지정하세요. 기본값: `Asia/Tokyo`
`songId`필수	경로	string	`songs` 리소스의 곡 ID(`musicId`).
`difficulty`필수	경로	string	`easy`, `normal`, `hard`, `expert`, `special`, `master` 중 곡의 `difficulty[].difficultyName`에 있는 값.
`format`필수	경로	string	원본 소재 PNG 또는 같은 PNG를 포함한 SVG.
`locale`선택	쿼리	string	제목과 밴드 이름의 언어: `ja`, `en`, `zh-TW`, `zh-CN`, `ko`. 기본값은 `Accept-Language` 협상.
`height`선택	쿼리	integer	채보 열의 높이(px, 360~1440). 헤더가 더해져 최종 이미지는 더 높습니다. `X-Haneoka-Image-Width`/`-Height`를 확인하세요. 기본값: `720`
`download`선택	쿼리	string	`1`은 `Content-Disposition: attachment`, `0`은 `inline`이라 브라우저 탭이나 `<img>`에서 보여 줄 수 있습니다. 기본값: `1`

요청 예시

cURL
JavaScript

curl -sS -o output.bin "https://haneoka.org/api/v1/servers/jp/songs/100001/charts/expert/image.png?height=540&locale=ja"

const response = await fetch("https://haneoka.org/api/v1/servers/jp/songs/100001/charts/expert/image.png?height=540&locale=ja");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const blob = await response.blob();

응답 예시

HTTP/2 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="Haneoka-jp-100001-expert-ja.png"
X-Haneoka-Server: jp

바이너리 본문(표시하지 않음).

오류

상태	코드	의미
`304`	—	`If-None-Match` 또는 `If-Modified-Since`가 일치했습니다. 캐시된 사본을 재사용하세요.
`400`	`invalid_time_zone`	유효한 IANA 시간대를 사용하세요.
`400`	`invalid_height`	`height`는 360~1440 사이의 정수여야 합니다.
`400`	`invalid_download`	`download`는 `0` 또는 `1`이어야 합니다.
`400`	`invalid_locale`	`locale`이 `ja`, `en`, `zh-TW`, `zh-CN`, `ko` 중 하나가 아닙니다.
`400`	`invalid_server`	`server`가 여러 번 전송되었거나 경로와 일치하지 않습니다.
`400`	`invalid_release`	`release`가 `r-` 뒤에 16진수 20자리가 아니거나 허용하지 않는 경로에 전송되었습니다.
`400`	`body_not_allowed`	채보 이미지 요청에는 본문을 넣을 수 없습니다.
`404`	`server_not_found`	서버 슬러그가 활성 리소스 서버가 아닙니다.
`404`	`song_not_found`	곡이 현재 릴리스에 없습니다.
`404`	`difficulty_not_found`	이 난이도의 채보가 없습니다.
`404`	`chart_not_found`	릴리스에 채보 파일이 없습니다.
`404`	`release_not_found`	요청한 릴리스를 이 서버에서 사용할 수 없습니다.
`406`	`format_not_supported`	확장자는 `svg` 또는 `png`여야 합니다.
`413`	`chart_too_large`	원본 채보가 렌더링 한도 2MiB를 초과합니다.
`413`	`chart_render_budget`	렌더링 결과가 픽셀 또는 SVG 한도를 초과합니다.
`502`	`chart_invalid`	릴리스의 채보를 해석하지 못했습니다.
`502`	`chart_path_invalid`	카탈로그의 채보 경로가 잘못되었습니다.
`502`	`png_invalid`	래스터라이저가 잘못된 PNG를 반환했습니다.
`502`	`chart_image_failed`	렌더링이 예기치 않게 실패했습니다.
`503`	`release_unavailable`	이 서버에는 아직 현재 릴리스가 게시되지 않았습니다.
`503`	`native_renderer_unavailable`	원본 이미지 서비스를 사용할 수 없습니다. 기기의 renderChartImage 모듈을 사용할 수 있습니다.