poly-pizza-api

Poly Pizza API v1.1

Poly Pizza (https://poly.pizza) では、CC0 および CC-BY の無料ローポリ 3D モデルを 10,000 点以上公開しています。 API を使うと、エージェントからプログラムでモデルを検索、絞り込み、ダウンロードできます。

認証

すべてのリクエストには、https://poly.pizza/settings/api で取得した API キーが必要です（無料アカウントが必要です）。この環境では、キーを POLY_PIZZA_KEY 環境変数から利用できます。ヘッダーとして渡してください：

X-Auth-Token: <your_api_key>

キーはすべてのリクエストに含める必要があります。OAuth フローはなく、固定トークンです。

ベース URL

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

以下のすべてのエンドポイントは、このベース URL からの相対パスです。

エンドポイント

モデルを検索

GET /search/{query}

キーワードに一致するモデルを返します。クエリ文字列は URL エンコードしてください。

クエリパラメーター：

パラメーター	型	デフォルト	説明
limit	integer	12	返す最大件数（最大約 50 件）
cursor	string	—	前回のレスポンスから取得したページネーションカーソル
format	string	"glb"	ファイル形式のフィルター（glb、fbx、obj）
animated	boolean	—	アニメーション付きモデルのみを対象にします
tricount	string	—	三角形ポリゴン数の範囲。例："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	OK
401	API キーがない、または無効です
404	モデル ID が見つかりません
429	レート制限を超過しました — 待機してください
500	サーバーエラー — 再試行してください

429 の場合は、再試行する前に少なくとも 1 秒待機してください。API のレート制限上限は公開されていません。個人利用は無料で、商用利用は従量課金制です。

---

よくあるパターン

キーワードに最適なモデルを見つける

1. GET /search/{keyword}?limit=5
2. 適切に見える結果のうち TriangleCount が最も小さいものを選びます。タスクでポリゴン数が指定されていない場合は、最初の結果を選びます。

シーン用にまとめて取得

必要なアセットの種類（例：「tree, rock, house, car」）をすべて洗い出し、キーワードごとに並列検索リクエストを送信します。各キーワードの最上位の結果を収集します。

クレジットを付けてダウンロード・保存

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 フレームワークでそのまま使用できます。
• 一部のモデルでは、Unity のネイティブインポーター用に DownloadFBX を利用できます。
• Thumbnail URL は JPEG のプレビュー画像です。ダウンロード前にプレビューを表示するのに便利です。
• モデル ID は固定されているため、後で ID を使ってキャッシュしたり参照したりしても安全です。
• API キーは、無料アカウントの作成後に https://poly.pizza/settings/api から取得できます。