Retrieving Assets
Asset endpoints provide access to game files, converting them into readily consumable file formats.
Game version pinning is supported for all asset endpoints. As assets do not have any direct connection with sheet data, there is no need to pin a schema.
A Word on Caching
Asset responses contain the converted asset file itself - effectively allowing for the “hotlinking” of the resulting file.
This is encouraged! Serving assets directly through XIVAPI makes it easy to keep them up to date between game versions, and can save a significant amount of disk space on a site-by-site basis. The API has several layers of caching in place to minimise undue load on the underlying asset service.
In saying this, please ensure that you are making use of the cache behavior we
provide. All asset endpoints include ETag headers in responses, and
will respect If-None-Match headers from clients.
Many web clients, including all browsers, will handle this behavior on your behalf. If you’re not sure, please reach out and we may be able to help check if it’s working.
Fetch Assets
Requests for an asset can be made using the asset’s path within the game files, and a format for the asset to be converted to. While technically valid requests, many path/format combinations are nonsensical, and will return an error - there’s no sensible way to format a 3D model as a PNG!
/api/asset?path=ui/loadingimage/-nowloading_base01_hr1.tex&format=png
Game paths can be found through a number of tools, including XIVAPI itself - icon fields in sheets will include paths to the associated icon asset in the response. Many other XIV data tools also facilitate finding the file path you’re looking for.
The accepted file formats is a dynamic list, and will expand as needs arise. Check the API reference for an up to date list of what is supported.
Compose Maps
For reasons associated with how maps function in the game, they are regularly split across a few files, and must be merged into a single image to look correct. To make this process simpler, the map asset endpoint is available, and performs this composition automatically when needed.
/api/asset/map/s1d1/00
At time of writing, the appropiate map IDs can be found in the Map sheet, or
through exploring the ui/map game file directory.