poly-pizza-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Poly Pizza API v1.1

Poly Pizza (https://poly.pizza) hosts 10,000+ free low-poly CC0 and CC-BY 3D models. The API lets agents search, filter, and download them programmatically.

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

Authentication

身份验证

All requests require an API key obtained from https://poly.pizza/settings/api (requires a free account). In this environment, the key is available as the

POLY_PIZZA_KEY

environment variable. Pass it as a header:

X-Auth-Token: <your_api_key>

The key must be present on every request. There is no OAuth flow — it's a static token.

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

X-Auth-Token: <your_api_key>

每个请求都必须包含该密钥。无需OAuth流程——这是一个静态令牌。

Base URL

基础URL

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

All endpoints below are relative to this base.

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

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

Endpoints

端点

Search models

搜索模型

GET /search/{query}

Returns models matching the keyword. URL-encode the query string.

Query parameters:

Param	Type	Default	Description
`limit`	integer	12	Max results to return (max ~50)
`cursor`	string	—	Pagination cursor from a previous response
`format`	string	`"glb"`	File format filter ( `glb` , `fbx` , `obj` )
`animated`	boolean	—	Filter to only animated models
`tricount`	string	—	Triangle count range, e.g. `"0-5000"`

Example:

http

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

Response shape:

json

{
  "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 /search/{query}

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

查询参数：

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

示例：

http

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

响应结构：

json

{
  "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 models

获取热门模型

GET /popular

Returns the most popular / trending models on the site.

Query parameters: same as search (

limit

cursor

format

animated

tricount

)

Example:

http

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

Response shape is identical to search.

GET /popular

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

查询参数： 与搜索接口相同（

limit

、

cursor

、

format

、

animated

、

tricount

）

示例：

http

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

响应结构与搜索接口完全一致。

Get model by ID

通过ID获取模型

GET /model/{id}

Returns full metadata for a single model by its unique ID.

Example:

http

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

Response is a single model object (same shape as an entry in

results

above).

GET /model/{id}

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

示例：

http

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

响应为单个模型对象（结构与上述

results

中的条目相同）。

Downloading a model

下载模型

The

Download

field in the response is a direct CDN URL to the

.glb

file. To download it, perform a plain GET request — no auth header required on the CDN URL itself.

python

import requests

响应中的

Download

字段是指向.glb文件的直接CDN URL。要下载该文件，只需执行普通的GET请求——CDN URL本身不需要身份验证头。

python

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)

---

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

---

Licenses and attribution

许可证与署名

License	Requirements
CC0	No attribution required — public domain
CC-BY 4.0	Must credit the creator. Format: `"[Title]" by [Username] (poly.pizza) CC-BY 4.0`

Always check

model.Licence

and record credits for CC-BY models. A minimal attribution line looks like:

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

许可证	要求
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

Pagination

分页

Responses include a

cursor

field. If it's non-null, there are more results. Pass it as

?cursor=<value>

on the next request (keep all other params the same).

python

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

响应包含

cursor

字段。如果该字段不为空，则表示还有更多结果。在下一次请求中传递

?cursor=<value>

（保持其他参数不变）即可获取下一页结果。

python

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

Error handling

错误处理

Status	Meaning
200	OK
401	Missing or invalid API key
404	Model ID not found
429	Rate limit exceeded — back off
500	Server error — retry

On 429, wait at least 1 second before retrying. The API has no documented rate limit ceiling; hobbyist use is free, commercial use is pay-as-you-go.

状态码	含义
200	请求成功
401	API密钥缺失或无效
404	模型ID不存在
429	请求频率超限——请暂停后重试
500	服务器错误——请重试

遇到429状态码时，请至少等待1秒后再重试。该API没有公开的频率上限；个人免费使用，商业使用采用按需付费模式。

Common patterns

常见使用模式

Find best match for a keyword

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

```
GET /search/{keyword}?limit=5
```
Pick the result with the lowest
```
TriangleCount
```
that still looks appropriate, or the first result if the task doesn't specify poly count.

```
GET /search/{keyword}?limit=5
```
选择三角形数量最少且符合需求的结果；如果任务未指定多边形数量，则选择第一个结果。

Batch fetch for a scene

批量获取场景所需资产

Identify all needed asset types (e.g. "tree, rock, house, car"), then fire parallel search requests for each keyword. Collect the top result per keyword.

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

Download and save with attribution

下载并保存带署名信息的模型

python

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}

python

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}

Notes

注意事项

Models are
```
.glb
```
(GLTF binary) by default, directly usable in Three.js, Babylon.js, Unity (with glTFast), Unreal, Godot, and most AR/VR frameworks.
```
DownloadFBX
```
is available on some models for Unity's native importer.
The
```
Thumbnail
```
URL is a JPEG preview image, useful for showing a preview before downloading.
Model IDs are stable — safe to cache and reference by ID later.
The API key is obtained from https://poly.pizza/settings/api after creating a free account.

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