API 调用与筛选

实例方法

方法	公共 GET 端点	返回值
`getTypes()`	`/types`	`hdris/textures/models` 数组
`getAssets(params)`	`/assets`	资产 ID → 元数据表
`getInfo(id)`	`/info/{id}`	单个资产元数据
`getFiles(id)`	`/files/{id}`	文件变体树
`getAuthor(id)`	`/author/{id}`	作者数据
`getCategories(assetType="all",within)`	`/categories/{type}`	旧分类计数或类型计数
`getTaxonomy(assetType)`	`/taxonomy/{type}` 或 `/taxonomy`	分类树与属性模式
`search(text,params)`	`/search`	排名结果及 total 等信息

覆盖核对时的公开 OpenAPI 文档全部 9 个路径。不包装后台管理、鉴权或未文档化端点。

结果保留服务端 JSON 结构，不固定所有字段。元数据中的 type 是数字：0 HDRI、1 材质、2 模型；查询参数的 type/t 则是字符串。

分类和属性筛选

import web.rest.polyHaven;
var ph = web.rest.polyHaven("My3DTool/1.0");

var schema,err = ph.getTaxonomy("models");
if(!schema) { ph.close();return null,err; }
print(schema.categories,schema.attributes);

// 属性名、枚举值以 taxonomy 的实际响应为准。
var assets,err = ph.getAssets({
    type="models";
    material=["wood","metal"]
});
ph.close();
if(!assets) return null,err;
for id,asset in assets { print(id,asset.name); }

category 是单一路径分类，支持官方 canonical path 或 slug path；父类包含子类。
categories 是旧分类数组/逗号分隔字符串，不等同于 category。
getAssets、search 的数组值会转换为 CSV；布尔值转为 true/false 字符串。数值 0 保留，输入参数表不变。
不替调用方构造 taxonomy 中不存在的属性；未知值产生的 HTTP 400 会原样返回。

搜索

import web.rest.polyHaven;
var ph = web.rest.polyHaven("My3DTool/1.0");
var hits,err = ph.search("mossy rock",{
    t="models";
    limit=10;
    min=0.35;
    future=false
});
ph.close();
if(!hits) return null,err;
for i,item in hits.results { print(item.slug,item.score); }

搜索词 trim/lower 以复用服务端等价查询缓存。results 数组顺序是排名；score 不一定能解释混合搜索顺序，不重新按 score 排序。total 可能大于 #results。通常保持 future=false，不要假定提前展示的资产已经可公开下载。

库不自动猜测搜索故障后的候选资产。HTTP 429/503 时由调用方决定等待或使用已有元数据做本地检索。

原生 web.rest 接口与错误

import web.rest.polyHaven;
var ph = web.rest.polyHaven("My3DTool/1.0");
ph.setTimeouts(15000,30000,30000);

// 保留原生接口。所有路径片段由 inet.url.encode 编码。
var api = ph.api();
var info,err,code = api.info["ceramic_vase_03"].get();
if(!info) {
    print(err,code,ph.lastStatusCode);
    print(ph.lastResponseError());
}
ph.close();

网络失败返回 null,err,code；封装自己的输入检查失败通常返回 null,err。客户端 lastStatusCode、lastResponseString()、lastResponseError() 与 web.rest 一致。输入检查没有发起请求时，HTTP 状态仍属于上一次请求。

命名方法会处理 CSV 参数，原生 api().xxx.get(params) 不额外处理这些参数。遇到限流可读取服务端 Retry-After：应在请求前按 web.rest 规则注册所需响应头，例如请求前设置 ph.responseHeaders={["Retry-After"]=true}，请求后读取 ph.responseHeaders["Retry-After"]（只有字符串才是实际响应值）。每次请求前重新初始化，避免沿用上一次的值；没有响应头时不要杜撰等待时间。

Markdown 格式