API dla developerów

Cały publiczny katalog symboli jest dostępny przez REST API — odczyt nie wymaga uwierzytelniania. Buduj aplikacje AAC na wspólnej bibliotece zamiast utrzymywać własne zestawy grafik.

Szybki start

Wyszukaj symbol (uproszczona odpowiedź dla integracji):

curl "https://aacstandard.com/api/v1/public/symbols/search?q=woda&language=pl"

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "woda",
      "language_code": "pl",
      "image_url": "https://aacstandard.com/static/symbols/pl/….png",
      "thumbnail_url": "https://aacstandard.com/static/thumbs/256/symbols/pl/….webp"
    }
  ],
  "count": 1
}

Najważniejsze endpointy

`GET /api/v1/public/symbols/search`	wyszukiwanie: `q`, `language`, `age_group` (child \| youth \| adult \| all), `limit`, `offset`
`GET /api/v1/symbols`	pełna lista z metadanymi i tłumaczeniami (paginowana)
`GET /api/v1/symbols/search`	filtry: `q`, `tags`, `age_group`, `has_audio`, `lang`…
`GET /api/v1/symbols/:id`	pojedynczy symbol z pełnymi metadanymi
`GET /api/v1/symbols/:id/variant`	wariant postaci: `skin=1–5`, `hair`, `mono=1`, `overlay=plural\|negation` → PNG
`GET /api/v1/symbols/:id/audio`	nagranie nazwy symbolu (TTS) w wybranym języku
`GET /api/v1/translations/languages`	lista obsługiwanych języków
`GET /api/v1/public/stats`	liczby: symbole, języki, grupy

Obrazy i miniatury

Oryginały PNG (1024×1024) są serwowane z /static/<ścieżka>, a lekkie miniatury WebP z /static/thumbs/{256|512}/<ścieżka .webp> — do siatek wyników używaj miniatur (~9 KB zamiast ~800 KB). Odpowiedzi mają nagłówki cache (max-age + stale-while-revalidate), a miniatury są immutable przez tydzień.

Zasady

Kanoniczny prefiks to /api/v1 — alias /api działa, ale jest oznaczony nagłówkiem Deprecation i zniknie z końcem 2027 r.
Endpointy publiczne mają limity zapytań (rate limiting) — cache'uj odpowiedzi po swojej stronie.
Użycie symboli w produkcie komercyjnym wymaga zgody — zobacz licencję. Dla partnerów istnieje osobne API zgłaszania brakujących symboli.

Pełna referencja API (wszystkie parametry i kody błędów) jest w przygotowaniu do publikacji — w razie pytań: hello@aisay.co.