譜面圖片

與網頁下載共用原生音符圖集、滑條、封面、圖示、字型與圖片排版。固定 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 模組。