api.polyzon.org · v1

Polyzon API

Поиск 3D-моделей по каталогу Polyzon со всех площадок и карточки моделей — для ваших ботов, сайтов и приложений.

Как начать

Войдите в аккаунт Polyzon, в разделе «API» создайте токен и сохраните его — второй раз он показан не будет.
Передавайте токен в каждом запросе: Authorization: Bearer pzk_…
Проверьте его методом GET /v1/me — здесь же, в песочнице ниже.

const res = await fetch('https://api.polyzon.org/v1/search?q=дракон&free=1', {
  headers: { Authorization: `Bearer ${process.env.POLYZON_TOKEN}` }
});
const { items, hasMore } = await res.json();

import os, requests

r = requests.get("https://api.polyzon.org/v1/search",
                 params={"q": "дракон", "sources": "printables"},
                 headers={"Authorization": f"Bearer {os.environ['POLYZON_TOKEN']}"})
r.raise_for_status()
print(r.json()["items"])

Лимиты

200 запросов в сутки (сброс в 00:00 UTC) и 20 в минуту — на аккаунт, сколько бы токенов у него ни было.
/v1/me и /v1/limits суточную квоту не тратят, но входят в минутный лимит.
Каждый ответ несёт X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунды Unix) для суточной квоты; ответ 429 — ещё и Retry-After.
Отозванный в аккаунте токен перестаёт работать в течение минуты.

Ошибки

Ошибки приходят как application/problem+json: поле code стабильно, по нему и ветвитесь; detail — пояснение для человека.

Статус	code	Когда
400	`bad_request`	Неверный параметр; в поле param — какой
400	`page_too_deep`	page × size больше 2400
401	`unauthorized`	Нет заголовка Authorization
401	`invalid_token`	Токен неверен или отозван
403	`account_action_required`	Примите действующие условия в аккаунте Polyzon
404	`not_found`	Нет такой модели или метода
410	`gone`	Модель удалена по требованию правообладателя
429	`rate_limited`	Превышен минутный лимит
429	`quota_exceeded`	Исчерпана суточная квота
503	`unavailable`	Сервис временно недоступен — повторите позже

Правила

В v1 поля только добавляются: переименование или удаление — только в новой версии. Неизвестные поля игнорируйте.
Модель, на которую пришёл 410 gone, удалена по требованию правообладателя — удалите её и у себя.
Показывая модели, ссылайтесь на страницу площадки (url) и указывайте автора — данные принадлежат площадкам и авторам.
Не храните токен в коде сайта или приложения у пользователя: только на своём сервере.

Методы и песочница

Токен Хранится только в этой вкладке; запросы из песочницы тратят ваши лимиты.

GET `/v1/search`

Поиск моделей. Поиск по каталогу Polyzon: модели со всех площадок, с фильтрами и страницами. Глубина выдачи — не больше 2400 моделей (page × size).

Параметр	Где	Описание
`q`*	запрос	Поисковый запрос на русском или английском, до 200 символов.
`page`	запрос	Номер страницы, с 1. По умолчанию `1`.
`size`	запрос	Моделей на странице. page × size — не больше 2400. По умолчанию `20`.
`sort`	запрос	Порядок: relevant — по релевантности, popular — по популярности на своей площадке, newest — новые, likes, makes, downloads. По умолчанию `relevant`.
`free`	запрос	Только бесплатные модели.
`sources`	запрос	Площадки через запятую: thingiverse, cults3d, printables, makerworld, 3dtoday, crealitycloud, myminifactory, thangs, youmagine, grabcad, sketchfab, threeding, nexprint, nasa, nih3d, smithsonian, pinshape, cgtrader, gambody, jewelmodel, makeronline, 3dexport.
`formats`	запрос	Форматы файлов через запятую: stl, 3mf, obj, step, scad, gcode и другие.
`license`	запрос	Лицензии через запятую: cc0, cc-by, cc-by-sa, cc-by-nd, cc-by-nc, cc-by-nc-sa, cc-by-nc-nd, gpl, lgpl, mit, bsd, private-use, commercial, custom, unknown.
`lang`	запрос	Язык названий и тегов: ru или en. Если оригинал на другом языке, отдаётся машинный перевод. По умолчанию `ru`.

curl -G "https://api.polyzon.org/v1/search" \
  -H "Authorization: Bearer $POLYZON_TOKEN" \
  --data-urlencode "q=дракон" \
  --data-urlencode "page=1" \
  --data-urlencode "size=20" \
  --data-urlencode "sort=relevant" \
  --data-urlencode "lang=ru"

Пример ответа

Страница выдачи. hasMore — есть ли следующая страница в пределах 2400; partial — часть каталога не ответила, выдача неполная. В stats.collects — сохранения в коллекции, а если площадка их не считает — скачивания.

{
  "query": "дракон",
  "correctedQuery": null,
  "didYouMean": null,
  "total": 1873,
  "totalRelation": "eq",
  "page": 1,
  "size": 20,
  "hasMore": true,
  "partial": false,
  "items": [
    {
      "source": "thingiverse",
      "id": "tv-1234567",
      "title": "Дракон с подвижными сочленениями (пример)",
      "url": "https://www.thingiverse.com/thing:1234567",
      "thumbnail": "https://cdn.thingiverse.com/assets/dragon.jpg",
      "creator": "example_maker",
      "license": "cc-by-nc",
      "price": {
        "type": "free",
        "value": 0,
        "currency": null,
        "display": "Бесплатно"
      },
      "formats": [
        "stl"
      ],
      "tags": [
        "дракон",
        "игрушка"
      ],
      "stats": {
        "likes": 51234,
        "comments": 870,
        "makes": 3120,
        "collects": 61000
      },
      "publishedAt": "2021-01-17T10:21:00Z"
    }
  ]
}

GET `/v1/models/{source}/{id}`

Карточка модели. Модель по площадке и её id — те же, что в элементах поиска и в адресе страницы polyzon.org/model/{source}/{id}. Картинки — адреса на CDN самой площадки.

Параметр	Где	Описание
`source`*	путь	Площадка, откуда модель.
`id`*	путь	Идентификатор модели на площадке с префиксом Polyzon, например tv-1234567.
`lang`	запрос	Язык названия, описания и тегов: ru или en. По умолчанию `ru`.

curl -G "https://api.polyzon.org/v1/models/thingiverse/tv-1234567" \
  -H "Authorization: Bearer $POLYZON_TOKEN" \
  --data-urlencode "lang=ru"

Пример ответа

Модель. copies — та же модель на других площадках.

{
  "source": "thingiverse",
  "id": "tv-1234567",
  "title": "Дракон с подвижными сочленениями (пример)",
  "url": "https://www.thingiverse.com/thing:1234567",
  "thumbnail": "https://cdn.thingiverse.com/assets/dragon.jpg",
  "creator": "example_maker",
  "license": {
    "id": "cc-by-nc",
    "raw": "Creative Commons - Attribution - Non-Commercial"
  },
  "price": {
    "type": "free",
    "value": 0,
    "currency": null,
    "display": "Бесплатно"
  },
  "formats": [
    "stl"
  ],
  "tags": [
    "дракон",
    "игрушка"
  ],
  "stats": {
    "likes": 51234,
    "comments": 870,
    "makes": 3120,
    "collects": 61000,
    "downloads": 410000,
    "views": 990000
  },
  "publishedAt": "2021-01-17T10:21:00Z",
  "description": "Дракон печатается целиком, без поддержек…",
  "images": [
    "https://cdn.thingiverse.com/assets/dragon.jpg"
  ],
  "creatorUrl": "https://www.thingiverse.com/example_maker",
  "category": "Toys & Games",
  "updatedAt": "2021-02-02T08:00:00Z",
  "copies": [
    {
      "source": "printables",
      "id": "pr-123456"
    }
  ]
}

GET `/v1/me`

Аккаунт и токен. Кому принадлежит токен, которым сделан запрос. Суточную квоту не тратит. Суточную квоту не тратит.

curl "https://api.polyzon.org/v1/me" \
  -H "Authorization: Bearer $POLYZON_TOKEN"

Пример ответа

Аккаунт и токен.

{
  "account": {
    "id": "0f8c2a4e-…",
    "displayName": "Алексей",
    "createdAt": "2026-03-14T10:00:00.000Z"
  },
  "token": {
    "id": "7d0e2f8a-…",
    "name": "Телеграм-бот",
    "prefix": "pzk_Q7xR2mVb",
    "createdAt": "2026-10-09T08:15:00.000Z"
  }
}

GET `/v1/limits`

Остаток лимитов. Минутное окно и сутки UTC: лимит, израсходовано, осталось и момент сброса (секунды Unix). Суточную квоту не тратит. Суточную квоту не тратит.

curl "https://api.polyzon.org/v1/limits" \
  -H "Authorization: Bearer $POLYZON_TOKEN"

Пример ответа

Окна квот аккаунта.

{
  "perMinute": {
    "limit": 20,
    "used": 1,
    "remaining": 19,
    "resetAt": 1791579180
  },
  "daily": {
    "limit": 200,
    "used": 37,
    "remaining": 163,
    "resetAt": 1791590400
  }
}

Как начать

Лимиты

Ошибки

Правила

Методы и песочница

GET /v1/search

GET /v1/models/{source}/{id}

GET /v1/me

GET /v1/limits

GET `/v1/search`

GET `/v1/models/{source}/{id}`

GET `/v1/me`

GET `/v1/limits`