Referencja API

Klucz API

Każde zapytanie (poza openapi.json i /api/health) wymaga klucza w jednym z nagłówków. W przeglądarce, w której jesteś zalogowany, klucz nie jest potrzebny.

Authorization: Bearer fsb_…
# albo
X-Api-Key: fsb_…

Do pięciu kluczy na konto, zarządzasz nimi w ustawieniach konta. Klucz działa jak hasło tylko do odczytu: nie wrzucaj go do repozytorium ani do kodu, który zobaczą inni.

Limity

Zapytania API

120 na minutę na konto, wspólnie dla wszystkich kluczy. Stan limitu podają nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (koniec okna, Unix w sekundach).

Pobieranie plików

Bez dziennego limitu, z przerwą przeciw masowemu ściąganiu: 30 plików na minutę, dla zaufanych tłumaczy 60.

Po przekroczeniu

Dostajesz 429 i nagłówek Retry-After z liczbą sekund do odczekania.

Pamięć podręczna

Odpowiedzi z kluczem mają Cache-Control: private. Wyniki zmieniają się rzadko, więc zapisuj je u siebie na kilka minut.

Paginacja

Listy zwracają data i pagination. Kolejne strony pobierasz parametrami page i limit (maksymalnie 100).

{
  "data": [ … ],
  "pagination": { "page": 1, "limit": 20, "total": 143, "totalPages": 8 }
}

Błędy

Każdy błąd ma ten sam kształt, a komunikat jest po polsku. Kod w polu code nadaje się do obsługi w programie.

{ "error": { "code": "unauthorized", "message": "API wymaga konta. …" } }

400 invalid_parameter

Zły parametr. Pole details wskazuje który i dlaczego.

401 unauthorized

Brak klucza, klucz błędny albo usunięty. Konto zbanowane też dostaje 401.

404 not_found

Nie ma takiej serii, napisów lub wersji, albo napisy są ukryte.

429 rate_limited

Za dużo zapytań. Poczekaj tyle, ile mówi Retry-After.

500 internal_error

Błąd po naszej stronie. Spróbuj ponownie za chwilę.

503 search_unavailable

Wyszukiwarka chwilowo nie działa. Dotyczy tylko /series z frazą q.

Endpointy

Wszystkie to GET. Każdy ma przykład do skopiowania, który zakłada klucz w zmiennej FANSUBY_KEY.

• /api/v1/matchNapisy do pliku wideo
• /api/v1/match/downloadPobierz najlepiej pasujące napisy
• /api/v1/seriesWyszukiwanie serii
• /api/v1/series/{id}Szczegóły serii
• /api/v1/series/{id}/episodesOdcinki serii
• /api/v1/subtitlesLista napisów
• /api/v1/subtitles/{id}Szczegóły napisów
• /api/v1/subtitles/{id}/downloadPobranie pliku napisów

curl -G -H "Authorization: Bearer $FANSUBY_KEY" \
  --data-urlencode "filename=Frieren - 05.mkv" \
  https://fansuby.cc/api/v1/match

curl -L -OJ -G -H "Authorization: Bearer $FANSUBY_KEY" \
  --data-urlencode "filename=Frieren - 05.mkv" \
  https://fansuby.cc/api/v1/match/download

curl -H "Authorization: Bearer $FANSUBY_KEY" "https://fansuby.cc/api/v1/series?q=frieren"

curl -H "Authorization: Bearer $FANSUBY_KEY" https://fansuby.cc/api/v1/series/anilist:154587

curl -H "Authorization: Bearer $FANSUBY_KEY" https://fansuby.cc/api/v1/series/mal:52991/episodes

curl -H "Authorization: Bearer $FANSUBY_KEY" \
  "https://fansuby.cc/api/v1/subtitles?anilistId=154587&episode=1&resolution=1080p"

curl -H "Authorization: Bearer $FANSUBY_KEY" https://fansuby.cc/api/v1/subtitles/42

curl -L -OJ -H "Authorization: Bearer $FANSUBY_KEY" https://fansuby.cc/api/v1/subtitles/42/download

Pola odpowiedzi

Wszystkie adresy są bezwzględne i prowadzą do fansuby.cc. Pola, których nie ma w danych, mają wartość null.

Seria

id, anilistId, malId, slug

Identyfikatory. malId bywa null.

title

Obiekt z romaji, english i native.

format, status, season, seasonYear

Wartości z AniList, np. TV, RELEASING, FALL, 2026.

episodesTotal

Zapowiedziana liczba odcinków, jeśli jest znana.

coverImage, coverImageMedium

Okładki w WebP (460×650 i 230×325). Hostujemy je sami, np. https://fansuby.cc/media/series/8/cover-3fa9….webp. Nazwa pliku zawiera skrót zawartości, więc adres się nie zmienia, dopóki obraz jest ten sam.

bannerImage

Baner w WebP (1800×450), jeśli seria go ma.

coverColor

Dominujący kolor okładki jako #rrggbb. Przydaje się do tła albo akcentu.

subtitleCount

Liczba opublikowanych napisów.

isAdult, url

Oznaczenie 18+ i adres strony serii.

Szczegóły serii (/series/{id}) dodają:

description

Oryginalny opis po angielsku, z AniList.

descriptionPl

Automatyczne tłumaczenie opisu na polski. Null, gdy go jeszcze nie ma albo opis się zmienił i czeka na nowe.

synonyms, genres, studios

Listy tekstów.

startDate, endDate, episodeDurationMin

Daty (YYYY-MM-DD) i długość odcinka w minutach.

episodeCount

Liczba odcinków w naszym katalogu.

averageScore, popularity

Ocena 0 do 100 i popularność z AniList.

nextAiringEpisode

Numer i czas (airingAt) najbliższego odcinka albo null.

relations

Powiązane serie: relationType, tytuł, seriesId i url, gdy jest w naszym katalogu.

links

Adresy anilist, mal i rss (kanał napisów serii).

Odcinek

id, number

Numer jest liczbą, więc zmieści też 12.5.

title

Obiekt z english, romaji i japanese.

airedAt

Data emisji albo null.

isFiller, isRecap

Oznaczenia odcinków specjalnych.

subtitleCount, url

Liczba napisów i adres strony odcinka.

Napisy

id, url, downloadUrl

Identyfikator, strona dla ludzi i bezpośredni adres pliku bieżącej wersji.

language, format

Język (pl) oraz ass albo srt.

releaseGroup, releaseSource, resolution

Do jakiego wydania wideo pasują, np. SubsPlease, WEB-DL, 1080p.

releaseFilename, alsoCompatible

Nazwa pliku wideo i inne wydania z pasującym timingiem.

videoDurationMs

Długość wideo, do którego zrobiono napisy.

version, sha256, sizeBytes

Numer bieżącej wersji, suma kontrolna i rozmiar pliku.

hasTypesetting, hasKaraoke, fonts

Czy plik ma typesetting i karaoke oraz jakich czcionek używa.

credits

Ekipa: role (translation, proofreading, typesetting, timing, editing, karaoke), nazwa i username.

group, uploader

Grupa tłumaczy i osoba, która wgrała napisy. Mogą być null.

series, episode

Skrót serii i odcinka, do którego należą.

downloadCount, notes

Liczba pobrań i uwagi tłumacza.

createdAt, updatedAt, versionCreatedAt

Daty dodania, zmiany i wydania bieżącej wersji.

/subtitles/{id} dodaje versions: numer, listę zmian, sumę kontrolną, rozmiar, liczbę linii i adres pobrania każdej wersji.

Kanały RSS i stan serwisu

Do śledzenia nowości nie odpytuj API w pętli. Kanały RSS nie wymagają klucza:

/rss

Najnowsze napisy z całego serwisu.

/seria/{slug}/rss

Napisy do jednej serii. Adres jest też w polu links.rss.

/grupa/{slug}/rss

Napisy jednej grupy tłumaczy.

/tlumacz/{username}/rss

Napisy jednego tłumacza. Działa też pod /uzytkownik/{username}/rss.

/api/health

Stan serwisu dla monitoringu: 200, gdy baza, wyszukiwarka i magazyn plików działają, inaczej 503. Bez klucza.

Specyfikacja OpenAPI

Pełny opis w formacie OpenAPI 3.1 jest pod /api/v1/openapi.json i działa bez klucza. Wczytasz go do Postmana albo generatora klientów dla swojego języka.

Dobre praktyki

• Szukaj serii po AniList lub MAL ID, nie po tytule. Tytuły się różnią, ID nie.
• Do jednego pliku wideo użyj /match. Zastępuje trzy osobne zapytania.
• Do synchronizacji używaj parametru since zamiast pobierania całej listy za każdym razem.
• Zapisuj odpowiedzi na kilka minut. Lista napisów do odcinka zmienia się rzadko.
• Po 429 czekaj tyle, ile mówi Retry-After, zamiast ponawiać od razu.
• Pokazuj autorów (pole credits) i link do strony napisów. To ich praca.