poly-pizza-api

Poly Pizza API v1.1

Poly Pizza (https://poly.pizza) 托管了 10,000 多个免费的低多边形 CC0 和 CC-BY 3D 模型。该 API 允许 Agent 以编程方式搜索、筛选和下载这些模型。

身份验证

所有请求都需要 API 密钥，可从 https://poly.pizza/settings/api 获取（需要免费账户）。在此环境中，密钥可通过 POLY_PIZZA_KEY 环境变量获取。将其作为请求头传递：

X-Auth-Token: <your_api_key>

每个请求都必须携带密钥。没有 OAuth 流程——这是一个静态令牌。

基础 URL

https://api.poly.pizza/v1/

以下所有端点均相对于此基础 URL。

端点

搜索模型

GET /search/{query}

返回与关键词匹配的模型。请对查询字符串进行 URL 编码。

查询参数：

参数	类型	默认值	描述
limit	整数	12	返回结果的最大数量（最多约 50 个）
cursor	字符串	—	上一个响应中的分页游标
format	字符串	"glb"	文件格式筛选条件（glb、fbx、obj）
animated	布尔值	—	仅筛选动画模型
tricount	字符串	—	三角形数量范围，例如 "0-5000"

示例：

GET https://api.poly.pizza/v1/search/tree?limit=5
X-Auth-Token: your_key_here

响应结构：

{
  "cursor": "some_cursor_string_or_null",
  "results": [
    {
      "ID": "5EGWBMpuXq",
      "Title": "Oak Tree",
      "Description": "A simple low poly oak tree",
      "Creator": {
        "Username": "someartist",
        "PURL": "https://poly.pizza/u/someartist"
      },
      "Thumbnail": "https://...jpg",
      "Download": "https://...glb",
      "DownloadFBX": "https://...fbx",
      "Licence": "CC-BY 4.0",
      "Tags": ["nature", "tree", "foliage"],
      "TriangleCount": 320,
      "Animated": false,
      "PublishedAt": "2021-08-15T04:32:11.000Z"
    }
    // ... more results
  ]
}

---

获取热门模型

GET /popular

返回网站上最受欢迎／热门的模型。

**查询参数：**与搜索相同（limit、cursor、format、animated、tricount）

示例：

GET https://api.poly.pizza/v1/popular?limit=10
X-Auth-Token: your_key_here

响应结构与搜索相同。

---

按 ID 获取模型

GET /model/{id}

根据模型的唯一 ID 返回单个模型的完整元数据。

示例：

GET https://api.poly.pizza/v1/model/5EGWBMpuXq
X-Auth-Token: your_key_here

响应是单个模型对象（结构与上文 results 中的条目相同）。

---

下载模型

响应中的 Download 字段是指向 .glb 文件的直接 CDN URL。要下载文件，只需发送普通 GET 请求——CDN URL 本身无需身份验证请求头。

import requests

# First, search for the model
headers = {"X-Auth-Token": api_key}
resp = requests.get("https://api.poly.pizza/v1/search/chair", headers=headers, params={"limit": 1})
model = resp.json()["results"][0]

# Then download the .glb directly
glb_bytes = requests.get(model["Download"]).content
with open(f"{model['Title']}.glb", "wb") as f:
    f.write(glb_bytes)

---

许可证和署名

许可证	要求
CC0	无需署名——属于公有领域
CC-BY 4.0	必须注明创作者。格式："[Title]" by [Username] (poly.pizza) CC-BY 4.0

请务必检查 model.Licence，并记录 CC-BY 模型的署名信息。最简署名行如下：

"Oak Tree" by someartist (https://poly.pizza/u/someartist) CC-BY 4.0

---

分页

响应中包含 cursor 字段。如果该字段不为 null，则表示还有更多结果。在下一个请求中将其作为 ?cursor=<value> 传递（其他参数保持不变）。

results = []
cursor = None
while True:
    params = {"limit": 24}
    if cursor:
        params["cursor"] = cursor
    data = requests.get(url, headers=headers, params=params).json()
    results.extend(data["results"])
    cursor = data.get("cursor")
    if not cursor:
        break

---

错误处理

状态码	含义
200	成功
401	缺少或无效的 API 密钥
404	未找到模型 ID
429	超出速率限制——请稍后重试
500	服务器错误——请重试

收到 429 时，至少等待 1 秒再重试。API 未公布速率限制上限；个人爱好用途免费，商业用途按使用量付费。

---

常见模式

查找与关键词最匹配的模型

1. GET /search/{keyword}?limit=5
2. 选择 TriangleCount 最低且仍然合适的结果；如果任务未指定多边形数量，则选择第一个结果。

为场景批量获取

确定所需的所有资源类型（例如“树、岩石、房屋、汽车”），然后针对每个关键词并行发送搜索请求。收集每个关键词的首个结果。

下载并保存署名信息

import requests, os

def fetch_model(api_key: str, keyword: str, out_dir: str) -> dict:
    headers = {"X-Auth-Token": api_key}
    r = requests.get(
        f"https://api.poly.pizza/v1/search/{keyword}",
        headers=headers,
        params={"limit": 1}
    )
    r.raise_for_status()
    results = r.json().get("results", [])
    if not results:
        raise ValueError(f"No models found for '{keyword}'")
    
    model = results[0]
    glb = requests.get(model["Download"])
    glb.raise_for_status()
    
    safe_name = model["Title"].replace(" ", "_")
    path = os.path.join(out_dir, f"{safe_name}.glb")
    with open(path, "wb") as f:
        f.write(glb.content)
    
    attribution = None
    if "CC-BY" in model.get("Licence", ""):
        attribution = (
            f'"{model["Title"]}" by {model["Creator"]["Username"]} '
            f'({model["Creator"]["PURL"]}) {model["Licence"]}'
        )
    
    return {"path": path, "model": model, "attribution": attribution}

---

说明

• 模型默认采用 .glb（GLTF 二进制）格式，可直接用于 Three.js、Babylon.js、Unity（搭配 glTFast）、Unreal、Godot 和大多数 AR/VR 框架。
• 部分模型提供 DownloadFBX，可用于 Unity 的原生导入器。
• Thumbnail URL 是 JPEG 预览图片，可用于下载前展示预览。
• 模型 ID 稳定，可安全缓存并在之后通过 ID 引用。
• 创建免费账户后，可从 https://poly.pizza/settings/api 获取 API 密钥。