谱面图片

与网页下载共用原生音符图集、滑条、封面、图标、字体与图片排版。固定 release 可复现输入；浏览器服务生成 PNG，SVG 内嵌同一 PNG。整张谱面分栏排布。设备端导出见本地计算指南。ETag 包含版本、图片选项与内容哈希。

渲染谱面

渲染谱面图片

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

用 ?server=（默认 intl）选择服务器的简写形式，行为与下方限定形式完全相同。

认证: 无需认证，可匿名公开读取。
缓存: public, max-age=300, must-revalidate

参数

名称	位置	类型	说明
`release`可选	查询	string	固定到不可变的发布版本，格式为 `r-` 加 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	每列谱面的高度（像素，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-` 加 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`	原始谱面超过 2 MiB 渲染上限。
`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-` 加 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	每列谱面的高度（像素，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-` 加 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`	原始谱面超过 2 MiB 渲染上限。
`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 模块。