# web.rest.polyHaven

基于 `web.rest.jsonLiteClient` 的 Poly Haven 公共 API 调用和按需下载库。版本 0.1.0。

目标：让 aardio 脚本、`process.blender` 和 Blender 技能工作流取得所需的 HDRI、模型和材质；库本身不依赖 Blender，不启动 UI、不修改 Blender 场景。

## 快速开始

```aardio
import web.rest.polyHaven;

// 正式应用请换成自己软件的名称、版本；不要伪装成浏览器。
var ph = web.rest.polyHaven(userAgent="My3DTool/1.0");

var hits,err = ph.search("ceramic vase",{t="models";limit=5});
if(!hits) { ph.close();return null,err; }
print(hits.results); // 保留 API 返回的相关性顺序

// 固定选择示例资产，不假定搜索第一项永远相同。
var asset,err,partial = ph.downloadAsset(
    "ceramic_vase_03",
    io.fullpath("/assets/ceramic_vase_03/1k"),
    {resolution="1k";maxBytes=16*1024*1024}
);
ph.close();
if(!asset) return null,err,partial;

print("Poly Haven",asset.mainFile);
return asset;
```

默认 HDRI 选择 `hdri/1k/exr`，模型和材质选择 `blend/1k/blend`。严格匹配，不擅自改为更大分辨率或其他格式。`.blend` 的 `include` 贴图会一并下载到原有相对路径。

## 文档

- [API 调用与筛选](api.html)
- [下载、校验与取消](download.html)
- [交给 Blender 使用](blender.html)
- [实现依据与边界](implementation.html)

API 库参考由源码智能提示自动生成。`api()`、`get()`、`receiveFile()`、`setTimeouts()`、代理、HTTP 状态和错误响应等仍继承自 `web.rest`。

## 使用约定

- 网络方法同步执行，GUI 中请放到工作线程，在线程内创建并关闭客户端，不跨线程共享实例。
- 不批量镜像整个站点。先搜索/筛选，再查询单个 `/files/{id}`，最后选择所需分辨率下载。
- API 元数据不做隐式缓存。调用方可复用 `getAssets/getFiles` 结果，或用 `JSON.save` 保存计划，再以 `download` 复用；需要更新时重新取清单。
- 下载缓存是现有文件：每次检查大小与 MD5，不只是判断文件存在。
- 默认拒绝覆盖不匹配的本地文件。确需更新时显式 `overwrite=true`。
- 不提供自动重试、断点续传或并发下载。失败后由调用方决定何时再试；已完成文件可校验复用。

## Poly Haven 服务要求

已于 2026-09-13 核对官方 `Public-API/ToS.md`：使用 live API 的软件应发送可识别软件名称的 User-Agent 或 Referer，并在向用户展示内容时清楚标注来源 Poly Haven。素材本身的 CC0 与 live API 服务条款是两件事。实际发布前请再核对官方条款。

本库默认 User-Agent 为 `aardio-polyHaven/0.1.0`，正式产品请自定义。界面中可使用“素材来源：Poly Haven”；这不表示官方背书。

官方 API：`https://api.polyhaven.com`

官方服务条款：`https://github.com/Poly-Haven/Public-API/blob/master/ToS.md`