Shufa API documentation
Shufa API documentation for dictionary lookup, public audio search, HSK vocabulary downloads, and Han character media. Requests use the API host and do not require authentication.
Primary host: https://api.shufa.study · Open the OpenAPI document
Dictionary lookup
Look up an exact Simplified or Traditional Chinese form, or search English definitions with lang=en and Russian definitions with lang=ru. Each result groups senses with pinyin, zhuyin, parts of speech, HSK or TOCFL levels, and audio links.
Audio search
Find public Mandarin recordings by an exact Simplified or Traditional Chinese word or character. The q parameter accepts up to 32 Unicode characters. A successful response includes the matching forms, locale, audio URL, and Shufa attribution. No match returns an empty results array.
Vocabulary downloads
List the published HSK vocabulary PDFs with their curriculum, level, vocabulary page, and direct Simplified and Traditional download URLs.
GET /api/downloads
Hanzi media
List the indexed characters with their code points and PNG and MP4 media URLs. Add q to select indexed characters from a Chinese string. Media may return 404 while an asset is not available.
Hanzi image and video files
Request a PNG or MP4 by using the media URL returned with a character. Media is served from the existing hanzi R2 bucket with public cache headers and ETags.
GET or HEAD /api/hanzi/media/{asset}
Requests and caching
The public endpoints are read-only and do not require authentication. Browser requests from https://shufa.study are allowed. Local development origins are enabled in the staging environment and the local Wrangler server. Cross-origin requests do not use credentials.
Audio and character indexes use public max-age=300 and s-maxage=3600. The downloads listing uses public max-age=3600. Hanzi media uses public max-age=3600 and s-maxage=3600. API responses include their existing cache headers.