REST API · v1

Dokumentacja API

Wysyłaj zdjęcia twarzy przez asynchroniczne API, korzystaj ze wspólnego portfela kredytów i śledź każde zadanie oraz obciążenie.

Centrum dla deweloperów

Połącz swoją aplikację z pomocą asystenta AI

Skopiuj ten prompt do ChatGPT, Claude, Cursor lub swojego asystenta programistycznego. Zapyta o używane przez Ciebie technologie, a potem przeprowadzi Cię przez konfigurację danych dostępowych, sprawdzenie salda, wysłanie zadania i weryfikację wyniku.

Otwórz zwykły tekst

Nie musisz wysyłać klucza API do AI. Prompt przeprowadzi Cię przez konfigurację go w środowisku własnego serwera.

Przeczytaj cały prompt / skopiuj ręcznie

# FAHR FACE API v1

Jesteś moim asystentem do integracji API. Pomóż mi w moim języku zintegrować to asynchroniczne API do szacowania wieku na podstawie zdjęcia twarzy z moim projektem. Przestrzegaj poniższych zasad. Jeśli aktualna dokumentacja różni się od nich, wyjaśnij różnicę, zanim zmienisz implementację. Nie wymyślaj punktów końcowych, SDK ani pól odpowiedzi.

Zacznij od pytań o mój język programowania, framework i wersję środowiska uruchomieniowego, o to, czy pracuję nad nowym czy istniejącym projektem, gdzie jest hostowany i czy mam dostęp do serwera oraz czy potrzebuję skryptu CLI, integracji z backendem czy funkcji internetowej. Jeśli możesz sprawdzić mój projekt, najpierw przejrzyj jego strukturę, zależności i przyjęte konwencje. Prowadź mnie po jednym małym, możliwym do zweryfikowania kroku naraz. Podawaj polecenia dla mojego systemu operacyjnego, lokalizacje plików, oczekiwane wyniki i wskazówki rozwiązywania problemów. Przed przejściem dalej poczekaj na moją odpowiedź. Kolejność: konfiguracja danych dostępowych → bezpłatne sprawdzenie salda → implementacja wysyłania obrazu → zapis i sprawdzanie statusu zadania → weryfikacja wyniku i rozliczenia. Nigdy nie twierdź, że niezrealizowane kroki zakończyły się powodzeniem.

Adres bazowy: https://fahrface.org. Dokumentacja: https://fahrface.org/developers; tworzenie kluczy: https://fahrface.org/settings/apikeys; doładowanie: https://fahrface.org/pricing. Poproś mnie o utworzenie klucza z terminem ważności i niewielkim limitem. Wymagane zakresy uprawnień: face-age:write, face-age:read, credits:read; usage:read jest potrzebne tylko do historii użycia. Tajny klucz jest wyświetlany tylko raz. Nigdy nie proś mnie o wklejenie prawdziwego klucza do czatu z AI. Użyj zmiennej środowiskowej FAHRFACE_API_KEY dostępnej wyłącznie na serwerze i wyklucz lokalne pliki z danymi dostępowymi z kontroli wersji. Nie umieszczaj kluczy w kodzie źródłowym, logach, przeglądarce ani aplikacji mobilnej, ani nie używaj prefiksów VITE_ lub NEXT_PUBLIC_. Frontend internetowy musi łączyć się z moim własnym serwerem proxy — to API nie obsługuje integracji przez CORS w przeglądarce.

Wszystkie endpointy korzystają z https://fahrface.org, a uwierzytelnianie odbywa się przez nagłówek Authorization: Bearer <FAHRFACE_API_KEY>. Odpowiedzi JSON zawierają pola code, message i data; sukces oznacza code=0. Żądanie POST ma typ multipart/form-data i dokładnie dwa pola: image (jeden plik JPEG, PNG lub WebP, maksymalnie 5 MiB, rzeczywisty format zgodny z MIME) oraz consent=appearance-age-2026-10-21. Nie obsługujemy zdalnych adresów URL obrazów, obrazów przesyłanych w formacie JSON, wielu plików ani dodatkowych pól. W przypadku FormData pozwól klientowi HTTP ustawić Content-Type wraz z boundary. Przed przesłaniem pliku rzeczywisty użytkownik musi wyraźnie potwierdzić, że ma ukończone 18 lat, przesyła własne zdjęcie i wyraża zgodę na jego przetwarzanie. Nie zaznaczaj zgody z góry ani nie potwierdzaj jej za użytkownika. Endpointy, zakresy i przykładowa odpowiedź:

POST /api/v1/face-age/jobs — face-age:write
GET /api/v1/face-age/jobs/JOB_ID — face-age:read
GET /api/v1/credits — credits:read
GET /api/v1/usage?page=1&pageSize=20 — usage:read

POST 202 / replay 200:
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

GET /api/v1/credits → data: available, reserved, testCost, priceVersion
GET /api/v1/usage → data: items, total, page, pageSize

Idempotencja: utworzenie zadania wymaga nagłówka Idempotency-Key z wartością zawierającą od 16 do 128 znaków ASCII: liter, cyfr, podkreśleń lub łączników (może to być UUID). Wygeneruj go raz dla każdego nowego, zamierzonego testu. Przed wysłaniem zapisz powiązanie klucza z dokładnymi bajtami oryginalnego pliku, typem MIME i zgodą. To samo konto, klucz i dane wejściowe zwrócą oryginalne zadanie bez ponownego obciążenia; inne dane wejściowe z tym samym kluczem zwrócą HTTP 409. W razie przekroczenia limitu czasu połączenia, ponawiania żądań lub restartu procesu użyj ponownie pierwotnego klucza i pliku. Nigdy nie generuj UUID w pętli ponawiania żądań. Ponowne wysłanie nieudanego zadania z tym samym kluczem nadal zwróci to zadanie; nowy klucz stosuj tylko wtedy, gdy użytkownik wyraźnie zleci nowy test.

Przepływ asynchroniczny: nowe zadanie zwraca HTTP 202, a ponowione żądanie — HTTP 200. Zapisz data.id. Odpytuj GET /api/v1/face-age/jobs/JOB_ID co 10–15 sekund, uwzględniając Retry-After i limit żądań dla klucza. Stany queued, processing i retrying oznaczają, że zadanie nie zostało jeszcze zakończone; succeeded i failed są stanami końcowymi. Po sukcesie odczytaj liczbową wartość data.age (w latach) i data.billingStatus, a po niepowodzeniu — data.error. Uruchamianie HF na zimno może potrwać kilka minut. Limit czasu wynosi 20 minut; aktywna dzierżawa procesu może opóźnić zakończenie o kolejne 4 minut, po czym zostanie uruchomione zaplanowane odzyskiwanie. Przekroczenie limitu czasu oczekiwania po stronie klienta nie oznacza, że zadanie na serwerze się nie powiodło. Zachowaj identyfikator zadania i umożliwiaj wznowienie odpytywania; nie twórz kolejnego płatnego testu.

Rozliczenia: każde żądanie API rezerwuje 1 kredytów. Po sukcesie opłata zostaje pobrana, a po ostatecznym niepowodzeniu zwrócona jednorazowo. Testy w witrynie kosztują 10 kredytów z tego samego portfela. Żądania GET są bezpłatne, ale wliczają się do limitu żądań. Najpierw sprawdź GET /api/v1/credits data.available: wartość ta już uwzględnia rezerwacje, więc nie odejmuj ponownie data.reserved. Żądania odrzucone przed utworzeniem zadania z powodu niewystarczającego salda, nieprawidłowego obrazu lub limitów nie powodują naliczenia opłaty. Limit konta: 60 uwierzytelnionych żądań na minutę, łącznie z zapytaniami; limity poszczególnych kluczy mogą być niższe. Jedno konto może mieć najwyżej dwa równoczesne zadania API; jeden klucz może dopuszczać tylko jedno. Limity klucza uwzględniają zarezerwowane i pobrane kredyty; zwroty zwalniają limit. Odwołane lub wygasłe klucze nie mogą wysyłać zapytań. Historia użycia obsługuje page/pageSize; maksymalna wartość pageSize to 100.

Błędy: sprawdzaj kod statusu HTTP i pole message, a nie tylko to, czy żądanie zostało wysłane. 400 nieprawidłowe żądanie, zgoda lub klucz idempotencji; 401 nieprawidłowy, wygasły lub odwołany klucz; 403 brak wymaganego zakresu; 402 za mało kredytów; 404 brak zadania lub inne konto; 409 konflikt danych wejściowych; 413 za duży plik; 415 nieprawidłowy format; 429 limit zapytań, równoczesnych zadań lub budżetu klucza; 503 usługa niedostępna. W przypadku błędów 400/401/402/403/413/415 popraw konfigurację lub dane wejściowe zamiast bezmyślnie ponawiać żądanie. Przy 409 przywróć pierwotne dane wejściowe; użyj nowego klucza tylko wtedy, gdy użytkownik celowo zleca nowy test. Przy 429 sprawdź message: w przypadku limitu zapytań lub równoczesnych zadań odczekaj zgodnie z Retry-After; przekroczenie budżetu klucza wymaga zmiany jego ustawień. Błędy sieciowe i 503 ponawiaj z ograniczonym opóźnieniem, zachowując klucz idempotencji żądania POST. Po błędach odpytywania zachowaj pierwotny identyfikator zadania.

Testy akceptacyjne: najpierw wykonaj bezpłatne sprawdzenie salda. Przed rzeczywistym przesłaniem pliku potwierdź ze mną, że mam odpowiedni portret, który przedstawia mnie i którego przetwarzanie akceptuję, oraz wyjaśnij, jak działa rezerwacja kredytów. Sprawdź, czy utworzenie zadania zwraca jego identyfikator, ponowienie żądania z tym samym plikiem i kluczem zwraca ten sam identyfikator, odpytywanie doprowadza do stanu końcowego, a w przypadku sukcesu zwracany jest szacowany wiek i naliczana jest dokładnie jedna opłata. Zweryfikuj też, czy po odświeżeniu lub ponownym uruchomieniu można wznowić odpytywanie. Jeśli brakuje środków lub zgody na rzeczywiste wywołanie, rzetelnie opisz weryfikację lokalną lub na danych testowych; nie twierdź, że integracja na żywo działa. Na koniec podaj instrukcję uruchomienia, nazwy zmiennych środowiskowych, zmienione pliki i wskazówki dotyczące rozwiązywania problemów. Nigdy nie ujawniaj prawdziwych sekretów ani zawartości zdjęć.

Prywatność i ograniczenia: zdjęcia są tymczasowo przechowywane w prywatnym miejscu i usuwane po zakończeniu przetwarzania; w razie problemów zadziała procedura awaryjnego usuwania po 24 godzinach. Portret przetwarza HF. Moja aplikacja nie powinna zapisywać zdjęć ani kluczy w logach i powinna usuwać pliki tymczasowe. Wynik to szacowany wiek widoczny na zdjęciu, a nie porada medyczna, weryfikacja tożsamości ani potwierdzenie wieku. Wersja 1 nie obsługuje wywołań zwrotnych webhook, zdalnych adresów URL obrazów ani endpointu do przesyłania wielu zdjęć; nie wymyślaj takich funkcji. Zacznij od pytania o mój stos technologiczny i środowisko wdrożeniowe, a potem poprowadź mnie przez pierwszy krok.

Rozliczenie

API: 1 kredyt za każdy udany test. Strona: 10 kredytów za test. Oba korzystają z tego samego portfela. Utworzenie zadania przez API rezerwuje 1 kredyt; końcowe niepowodzenie zwraca go jednorazowo.

Wysyłaj Authorization: Bearer z wymaganym zakresem uprawnień. Przy ponawianiu żądania z identycznymi danymi obrazu użyj tego samego Idempotency-Key. Ponowne użycie go z innymi danymi zwróci HTTP 409. Sprawdzanie statusu nie zużywa kredytów.

Punkty końcowe

HTTP	Uprawnienia
POST /api/v1/face-age/jobs	face-age:write
GET /api/v1/face-age/jobs/{id}	face-age:read
GET /api/v1/credits	credits:read
GET /api/v1/usage?page=1&pageSize=20	usage:read

Utwórz zadanie

Użyj multipart/form-data z jednym plikiem obrazu (JPEG, PNG lub WebP, do 5 MB) oraz podanym niżej polem zgody. Z tego punktu końcowego mogą korzystać wyłącznie osoby dorosłe, które przesyłają własne zdjęcie za zgodą. Zdalne adresy URL i dodatkowe parametry są odrzucane. Wygeneruj nowy klucz idempotencji tylko dla nowego testu.

# Wygeneruj i zapisz klucz raz dla każdego nowego testu; przy ponawianiu uruchom tylko poniższe curl z oryginalnym kluczem i obrazem.
IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

Sprawdź wynik

Utworzenie zadania zwraca HTTP 202 i identyfikator zadania. Sprawdzaj status co 10–15 sekund. queued, processing i retrying to stany pośrednie; succeeded i failed to stany końcowe. Wybudzanie HF może potrwać kilka minut. Zadania mają limit czasu 20 minut; aktywna dzierżawa procesu roboczego może opóźnić ostateczne odzyskiwanie nawet o kolejne cztery minuty.

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

Błędy i limity

Odpowiedzi mają format code/message/data. HTTP 400: nieprawidłowe żądanie lub zgoda; 401: nieprawidłowy lub wygasły klucz; 403: brak uprawnienia; 402: za mało kredytów; 404: nie znaleziono zadania lub nie należy ono do Ciebie; 409: zmienione dane wejściowe; 413/415: nieprawidłowy rozmiar lub typ obrazu; 429: limit żądań, równoczesności lub budżetu; 503: usługa niedostępna. Stosuj się do Retry-After, ponownie używaj tego samego klucza idempotencji i przed ponowieniem sprawdź message.

Klucze wygasają najpóźniej po roku. Limit obejmuje kredyty zarezerwowane i wykorzystane przy udanych testach; zwroty przywracają limit. Na koncie obowiązuje limit 60 żądań na minutę i maksymalnie dwóch aktywnych zadań API.

Zdjęcia twarzy są tymczasowo przechowywane w prywatnym zasobniku i usuwane po zakończeniu przetwarzania, z awaryjnym usunięciem po 24 godzinach. HF przetwarza zdjęcie; wyniki nie stanowią porady medycznej, weryfikacji tożsamości ani dowodu wieku.