Chart images

Uses the same native note atlas, ribbons, jacket, icons, fonts and image layout as the website download. Pin a release for reproducible inputs. PNG is rendered by a browser service; SVG contains that same PNG. The complete chart is arranged in columns. Device-side export is available in the local computation guide. ETag revalidation includes the release, image options and content hash.

Render a chart

Render a chart image

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

Short form that selects the server with ?server= (default intl). Behaves exactly like the scoped route below.

Authentication

None. Public, anonymous read.

Caching

public, max-age=300, must-revalidate

Parameters

Name	In	Type	Description
releaseoptional	query	string	Pin an immutable release, r- followed by 20 lowercase hex digits. Omit it to read the current release. See Servers and releases.
timeZoneoptional	query	string	IANA time zone for release dates. Use your browser time zone to match its download. Default: Asia/Tokyo
songIdrequired	path	string	Song ID (musicId) from the songs resource.
difficultyrequired	path	string	easy, normal, hard, expert, special or master — must exist in the song's difficulty[].difficultyName.
formatrequired	path	string	Native png, or svg embedding the same PNG.
localeoptional	query	string	Language of the title and band name: ja, en, zh-TW, zh-CN or ko. Defaults to the Accept-Language negotiation.
heightoptional	query	integer	Height of each chart column in pixels, 360–1440. The finished image is taller because it adds a header; read X-Haneoka-Image-Width / -Height. Default: 720
downloadoptional	query	string	1 sends Content-Disposition: attachment; 0 sends inline so the image can be shown in a browser tab or <img>. Default: 1
serveroptional	query	string	Resource server slug. Defaults to intl. Send it at most once. Default: intl

Example request

cURL

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

JavaScript

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();

Example response

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>

Trimmed for length; the real response contains more entries.

Errors

Status	Code	Meaning
304	—	If-None-Match or If-Modified-Since matched; reuse your cached copy.
400	invalid_time_zone	Use a valid IANA time zone.
400	invalid_height	height must be an integer from 360 to 1440.
400	invalid_download	download must be 0 or 1.
400	invalid_locale	locale is not one of ja, en, zh-TW, zh-CN, ko.
400	invalid_server	server was sent more than once or does not match the route.
400	invalid_release	release is not an r- followed by 20 hex digits, or was sent on a route that rejects it.
400	body_not_allowed	Chart image requests must not carry a body.
404	server_not_found	The server slug is not an active resource server.
404	song_not_found	The song is not in the current release.
404	difficulty_not_found	The song has no chart for this difficulty.
404	chart_not_found	The chart file is missing from the release.
404	release_not_found	The requested release is not available on this server.
406	format_not_supported	The extension must be svg or png.
413	chart_too_large	The raw chart exceeds the 2 MiB render budget.
413	chart_render_budget	The rendered image would exceed the pixel or SVG budget.
502	chart_invalid	The chart in the release could not be parsed.
502	chart_path_invalid	The catalog points to an invalid chart path.
502	png_invalid	The rasteriser returned an invalid PNG.
502	chart_image_failed	Rendering failed unexpectedly.
503	release_unavailable	No current release is published for the server yet.
503	native_renderer_unavailable	The native image service is unavailable. Use the device-side renderChartImage module.

Render a chart image for a server

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

Scoped form. A server query parameter, if sent, must equal the path value. Requests must not carry a body.

Authentication

None. Public, anonymous read.

Caching

public, max-age=300, must-revalidate

Parameters

Name	In	Type	Description
serverrequired	path	string	Resource server slug from GET /api/v1/releases, for example intl or jp.
releaseoptional	query	string	Pin an immutable release, r- followed by 20 lowercase hex digits. Omit it to read the current release. See Servers and releases.
timeZoneoptional	query	string	IANA time zone for release dates. Use your browser time zone to match its download. Default: Asia/Tokyo
songIdrequired	path	string	Song ID (musicId) from the songs resource.
difficultyrequired	path	string	easy, normal, hard, expert, special or master — must exist in the song's difficulty[].difficultyName.
formatrequired	path	string	Native png, or svg embedding the same PNG.
localeoptional	query	string	Language of the title and band name: ja, en, zh-TW, zh-CN or ko. Defaults to the Accept-Language negotiation.
heightoptional	query	integer	Height of each chart column in pixels, 360–1440. The finished image is taller because it adds a header; read X-Haneoka-Image-Width / -Height. Default: 720
downloadoptional	query	string	1 sends Content-Disposition: attachment; 0 sends inline so the image can be shown in a browser tab or <img>. Default: 1

Example request

cURL

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

JavaScript

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();

Example response

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

Binary body (not shown).

Errors

Status	Code	Meaning
304	—	If-None-Match or If-Modified-Since matched; reuse your cached copy.
400	invalid_time_zone	Use a valid IANA time zone.
400	invalid_height	height must be an integer from 360 to 1440.
400	invalid_download	download must be 0 or 1.
400	invalid_locale	locale is not one of ja, en, zh-TW, zh-CN, ko.
400	invalid_server	server was sent more than once or does not match the route.
400	invalid_release	release is not an r- followed by 20 hex digits, or was sent on a route that rejects it.
400	body_not_allowed	Chart image requests must not carry a body.
404	server_not_found	The server slug is not an active resource server.
404	song_not_found	The song is not in the current release.
404	difficulty_not_found	The song has no chart for this difficulty.
404	chart_not_found	The chart file is missing from the release.
404	release_not_found	The requested release is not available on this server.
406	format_not_supported	The extension must be svg or png.
413	chart_too_large	The raw chart exceeds the 2 MiB render budget.
413	chart_render_budget	The rendered image would exceed the pixel or SVG budget.
502	chart_invalid	The chart in the release could not be parsed.
502	chart_path_invalid	The catalog points to an invalid chart path.
502	png_invalid	The rasteriser returned an invalid PNG.
502	chart_image_failed	Rendering failed unexpectedly.
503	release_unavailable	No current release is published for the server yet.
503	native_renderer_unavailable	The native image service is unavailable. Use the device-side renderChartImage module.