web.rest.polyHaven

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

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

快速开始

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 调用与筛选
• 下载、校验与取消
• 交给 Blender 使用
• 实现依据与边界

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

Markdown 格式