Centrum pomocy GenderAPI.io V2
Najczęściej zadawane pytania
Odpowiedzi dotyczące zapytań V2, wskaźnika pewności, wyników bez prognozy, kredytów, prywatności i konta. Jeśli utrzymujesz integrację z poprzednią wersją, skorzystaj z dokumentacji V1.
Wyniki i pewność
Jak rozumieć prognozę i jej ograniczenia
Kontekst kraju, wskaźniki pewności i wyniki bez prognozy w API V2.
Czy wynik GenderAPI określa płeć konkretnej osoby?
Nie. GenderAPI wnioskuje o płci na podstawie sygnałów związanych z imieniem lub, gdy ta opcja jest włączona, z pseudonimem. Prognoza nie jest zweryfikowaną informacją o osobie. Zachowuj niepewność, szanuj tożsamość deklarowaną przez każdą osobę i nie opieraj decyzji o dużym znaczeniu wyłącznie na tym oszacowaniu.
Jak kontekst kraju wpływa na wynik?
Opcjonalny kod kraju ISO, zapisany wielkimi literami, dostarcza regionalnego kontekstu dla zapytania. Podawaj go tylko wtedy, gdy jest istotny i znany. To samo imię może być używane różnie w poszczególnych regionach; zwrócony kraj oznacza powiązanie imienia, a nie dowód obywatelstwa ani miejsca zamieszkania.
Co oznacza wskaźnik pewności w V2?
confidence to wartość od 0 do 1 albo null, gdy nie jest dostępna. Odczytuj ją razem z confidence_kind: observed_frequency oznacza liczbę wystąpień dominującej kategorii w zbiorze danych podzieloną przez łączną liczbę wystąpień; model_reported to wskaźnik podany przez AI. Nie są to skalibrowane prawdopodobieństwa dotyczące konkretnej osoby ani zmierzona dokładność produktu. Progi weryfikacji ustalaj na podstawie reprezentatywnych danych.
Co oznacza gender: null i czy taki wynik jest płatny?
Pomyślny wynik V2 z gender: null oznacza, że dostępne dowody nie pozwoliły ustalić płci. Jest to natywna wartość null w JSON, a nie ciąg znaków "null". Pomyślny wynik bez prognozy jest rozliczany według wybranej stawki. Zachowuj go jako nieznany; awaria dostawcy lub błąd zapytania to osobny rodzaj błędu.
Czy mogę wysyłać imiona zapisane w różnych systemach pisma?
Tak. Wysyłaj imiona w Unicode, z oryginalnymi znakami i istotnymi znakami diakrytycznymi. Pokrycie i pewność zależą od imienia, regionu i dostępnych dowodów, dlatego przetestuj reprezentatywną próbkę systemów pisma i krajów obsługiwanych przez Twoją aplikację.
API i AI
Wybór rodzaju zapytania i opcji AI
Rodzaje zapytań V2, partie, działanie AI i limity użycia.
Czy mogę analizować imiona, adresy e-mail i nazwy użytkowników w jednej partii?
Tak. POST /api/v2/gender/batch przyjmuje do 50 pozycji z kluczem API albo 10 w próbie dla adresu IP. Każda pozycja ma własne pola type, value, opcjonalne country i ustawienia AI. Domyślnie AI jest wyłączona dla pozycji w partii. Sprawdzaj każdy wynik: partia może zwrócić HTTP 200, mimo że niektóre pozycje zakończyły się błędem. Kredyty są naliczane za każdą pomyślnie przetworzoną pozycję, także za wyniki bez prognozy.
Jak działa zapytanie o adres e-mail?
Użyj type: email z prawidłowym adresem. API szuka użytecznego sygnału imienia w części lokalnej, przed znakiem @; domena nie określa tożsamości ani kraju osoby. Wspólne skrzynki i nieczytelne adresy mogą zwrócić wynik nieznany. Pojedyncze zapytanie domyślnie korzysta z AI, jeśli zbiór danych nie pozwala ustalić wyniku.
Jak działa zapytanie o nazwę użytkownika?
Użyj type: username. Zwykłe zapytanie szuka rozpoznawalnego imienia w identyfikatorze lub nazwie wyświetlanej. Abstrakcyjne pseudonimy mogą zwrócić wynik nieznany. Włącz forceToGenderize, jeśli po nierozstrzygniętym sprawdzeniu zbioru danych chcesz użyć AI uwzględniającej pseudonimy; ta opcja może zwrócić płeć bez wyodrębnienia prawdziwego imienia.
Kiedy V2 korzysta z AI?
Pojedyncze zapytania domyślnie używają options.ai_mode: fallback: najpierw sprawdzany jest zbiór danych, a jeśli płeć nie zostanie ustalona, używana jest AI, łącznie za 1 kredyt. off korzysta wyłącznie ze zbioru danych za 1 kredyt; always pomija zbiór danych i używa AI za 2 kredyty. Pozycje w partii mają domyślnie ustawienie off i mogą włączać AI indywidualnie. Żaden z tych trybów nie gwarantuje wyniku innego niż null.
Do czego służy forceToGenderize?
Ta opcjonalna flaga działa z imionami, adresami e-mail i nazwami użytkowników, także w poszczególnych pozycjach partii. Wynik ustalony na podstawie zbioru danych kosztuje 1 kredyt. W przeciwnym razie używana jest AI uwzględniająca pseudonimy, łącznie za 2 kredyty, nawet jeśli pomyślny wynik jest nieznany. Prawdziwe imię nie jest wymagane. Pomiń ai_mode lub użyj fallback; połączenie tej flagi z off lub always zwraca 422.
Jak naliczane są kredyty w V2?
Sprawdzaj meta.usage.charged_credits, aby poznać faktyczną opłatę za operację, oraz billing_status, aby sprawdzić jej potwierdzenie. Zwykłe prognozy ze zbioru danych i w trybie fallback kosztują 1 kredyt za każdą pomyślnie przetworzoną pozycję; always i AI uwzględniająca pseudonimy kosztują 2 kredyty. Wykonana weryfikacja numeru telefonu kosztuje 1 kredyt, także gdy wynik jest nieprawidłowy. Wystarczy dodatnie saldo początkowe, więc końcowa opłata może sprawić, że saldo stanie się ujemne. Kredyty za nieudane prognozy są zwracane; niepotwierdzone rozliczenie wymaga weryfikacji przez pomoc techniczną.
Czy V2 ma limity zapytań?
Tak. Obecne wartości domyślne to 120 zapytań na minutę na konto, 600 na minutę na adres IP i 2 równoczesne operacje na konto. Obowiązuje też wspólna przepustowość usługi. Treść zapytań POST jest ograniczona do 64 KiB; partie przyjmują 50 pozycji z kluczem albo 10 w próbie dla adresu IP. Respektuj HTTP 429 i Retry-After, zamiast zakładać, że zapytania zawsze będą przyjmowane aż do tych limitów.
Czy mogę ponowić nieudane zapytanie lub zapytanie, które przekroczyło limit czasu?
Każde zapytanie o prognozę jest nową operacją, rozliczaną w zwykły sposób. Przekroczenie limitu czasu lub utrata odpowiedzi nie dowodzi, że nie pobrano kredytów. Przed ponowieniem sprawdź billing_status; jeśli rozliczenie nie jest potwierdzone, skontaktuj się z pomocą techniczną, podając request_id. W przypadku częściowo nieudanej partii ponawiaj tylko pozycje zakończone błędem, gdy rozliczenie zostanie potwierdzone. Przy odpowiedzi 429 stosuj się do Retry-After.
Gdzie znajdę przykłady kodu i narzędzia dla V2?
Przewodniki V2 zawierają przykłady w cURL, JavaScript, Python, PHP, Java, C# i Go. Swagger i Postman korzystają z tego samego kontraktu V2. Wybierz rodzaj danych wejściowych i przechowuj klucz API w konfiguracji po stronie serwera.
Czy mogę nadal korzystać z V1?
Tak. Istniejące integracje V1 zachowują swoje dotychczasowe endpointy i formaty odpowiedzi. V1 i V2 korzystają z tego samego klucza API i salda kredytów, ale różnią się polami zapytań, odpowiedziami i błędami. Do utrzymania istniejącego klienta używaj osobnej dokumentacji V1, a gdy zechcesz go zaktualizować, skorzystaj z przewodnika po migracji.
Prywatność i pliki
Jak przetwarzane są dane
Gdzie znaleźć aktualne informacje o przetwarzaniu, przechowywaniu i usuwaniu danych.
Czy udane zapytania do GenderAPI są przechowywane?
Polityka prywatności wyjaśnia, jakie rekordy zapytań, rekordy operacyjne i logi bezpieczeństwa mogą być przechowywane, w jakim celu są przetwarzane i jak przebiega ich usuwanie. Zapoznaj się z tymi informacjami w kontekście swojej integracji i nie wysyłaj zbędnych danych osobowych.
Czy adresy e-mail wysyłane w zapytaniach są przechowywane?
Aktualne zasady przetwarzania adresów e-mail wysyłanych w zapytaniach i powiązanych rekordów technicznych opisuje Polityka prywatności. Adres e-mail może stanowić dane osobowe: wysyłaj tylko to, czego wymaga zapytanie, i nie zapisuj pełnych adresów we własnych logach diagnostycznych.
Jak długo przechowywane są przesłane pliki Excel lub CSV?
Polityka prywatności określa zasady przechowywania, usuwania i tworzenia kopii zapasowych przesłanych plików. Wyeksportuj potrzebne wyniki i usuń plik za pomocą opcji dostępnych w obszarze roboczym, gdy nie będzie już potrzebny. W sprawie wymagań Twojej organizacji dotyczących przechowywania danych skontaktuj się z pomocą techniczną.
Czy dostawcy usług mogą przetwarzać dane z zapytań lub przesłanych plików?
Polityka prywatności oraz informacje o podmiotach przetwarzających opisują przetwarzanie danych przez dostawców usług i stosowane zabezpieczenia. Zapoznaj się z tymi materiałami oraz z każdą umową obowiązującą dla Twojego konta, oceniając, gdzie przetwarzane są Twoje dane.
Polityka prywatności →Podmioty przetwarzające →Informacje o RODO →
Konto i pomoc
Podłączanie klucza i zarządzanie kontem
Bezpłatny dostęp, uwierzytelnianie, sprawdzanie salda i pomoc techniczna.
Czy mogę wypróbować GenderAPI bezpłatnie?
Tak. Zarejestrowane bezpłatne konto obejmuje 200 kredytów dziennie. Niezależnie od tego próba V2 bez klucza zapewnia 10 kredytów na publiczny adres IP w 24-godzinnym okresie, wspólnych z V1 i innymi użytkownikami tego adresu IP. W obu przypadkach obowiązują zwykłe stawki; liczba kredytów nie zawsze odpowiada liczbie zapytań HTTP.
Jak się uwierzytelnić i chronić klucz API?
Używaj Authorization: Bearer YOUR_API_KEY w zaufanym kodzie po stronie serwera; zapytania POST wymagają też Content-Type: application/json. Nie umieszczaj prawdziwego klucza w kodzie przeglądarki, publicznych repozytoriach ani logach. Brakujący, nieprawidłowo sformatowany lub nieznany klucz może skutkować użyciem próby dla adresu IP, dlatego sprawdzaj, czy meta.access.mode ma wartość api_key. Znane klucze, które zostały wyłączone, wygasły lub mają ograniczenia, nie przełączają się na próbę.
Jak sprawdzić pozostałe kredyty?
Wywołaj GET /api/v2/usage z kluczem Bearer. To sprawdzenie salda jest bezpłatne i zwraca data.remaining_credits. Bez klucza odczytuje wspólne saldo próby dla adresu IP. V1 i V2 korzystają z tego samego salda konta; wartość remaining_credits w prognozie odzwierciedla saldo w chwili zakończenia operacji.
Gdzie mogę zarządzać subskrypcją lub ją anulować?
Zaloguj się do aplikacji GenderAPI, aby zarządzać subskrypcją powiązaną z Twoim kluczem API. Aktualne ustawienia konta pozwalają sprawdzić pakiet i opcje anulowania.
Gdzie mogę zaktualizować dane rozliczeniowe?
Ustawieniami rozliczeń i płatności zarządzasz w aplikacji GenderAPI po zalogowaniu się na konto powiązane z danym kluczem API lub subskrypcją.
Jak zgłosić nieprawidłowy wynik lub poprosić o pomoc przy integracji?
Wyślij do pomocy technicznej wersję API, endpoint, request_id i krótki przykład pozwalający odtworzyć problem. Podaj kod błędu, jeśli jest dostępny, ale usuń klucz API i wrażliwe dane osobowe.
Baza wiedzy technicznej
Przewodniki wdrożeniowe i odpowiedzialne korzystanie
Odpowiedzi dotyczące wyników, prywatności i działania V2, z linkami do przewodników i wersją Markdown każdej odpowiedzi.
Wyniki, pewność i odpowiedzialne korzystanie
Nierozstrzygnięta prognoza V2 zwraca w polu gender natywną wartość null z JSON, a nie ciąg znaków "null". Imię może być niejednoznaczne albo dostępne dowody mogą być niewystarczające; sprawdź result_status i reason, jeśli są obecne. Zachowaj wynik nieznany, zamiast przypisywać go na siłę do którejś kategorii. Pomyślna prognoza bez wyniku jest rozliczana według wybranej stawki. Błędy zapytania lub dostawcy to osobne niepowodzenia, a informacje o ich rozliczeniu znajdziesz w meta.usage.
Przeczytaj pełną odpowiedź →Jak oceniana jest dokładność GenderAPI?Rzetelna ocena dokładności podaje badaną populację, datę, metodę doboru próby, odsetek wyników nieznanych oraz wyniki w podziale na regiony i systemy pisma. Obecna strona metodologii opisuje protokół oceny, a nie zmierzony procent dokładności. Pola confidence i confidence_kind w V2 wyjaśniają, na jakich dowodach opiera się każdy wynik; nie zastępują one oceny na reprezentatywnych danych.
Przeczytaj pełną odpowiedź →Źródła danych, prywatność i zgodność
Strona o pochodzeniu danych opisuje ramy dokumentowania kategorii źródeł, kryteriów wyboru, licencji oraz ograniczeń geograficznych i związanych z systemami pisma. Obecnie nie publikuje ona zweryfikowanego katalogu źródeł. Zapoznaj się z tą stroną i skontaktuj się z pomocą techniczną w sprawie wymagań dotyczących źródeł w Twojej integracji; nie zakładaj źródła, wielkości zbioru danych ani zakresu pokrycia, które nie zostały udokumentowane.
Przeczytaj pełną odpowiedź →Jak często aktualizowane są dane o imionach?Obecna strona o pochodzeniu danych nie podaje jednego harmonogramu aktualizacji dla wszystkich rekordów imion ani reguł przetwarzania. Jeśli aktualność danych ma znaczenie w Twoim przypadku, zapytaj pomoc techniczną o konkretny zbiór danych lub proces i oceń reprezentatywne wyniki. Data przeglądu strony nie dowodzi, że wszystkie powiązane rekordy zostały zaktualizowane w tym dniu.
Przeczytaj pełną odpowiedź →Gdzie znaleźć informacje o RODO i umowie powierzenia przetwarzania danych?Polityka prywatności, informacje o RODO, Umowa powierzenia przetwarzania danych i rejestr podmiotów przetwarzających opisują opublikowane warunki przetwarzania i zabezpieczenia. Zapoznaj się z aktualnymi dokumentami i każdą umową obowiązującą dla Twojego konta. W sprawach dotyczących Twojej organizacji, takich jak role w przetwarzaniu, przekazywanie danych lub żądania osób, których dane dotyczą, skontaktuj się z GenderAPI; ogólne FAQ nie zastępuje obowiązującej umowy.
Przeczytaj pełną odpowiedź →Działanie API, błędy i rozliczenia
Używaj Authorization: Bearer YOUR_API_KEY w zaufanym kodzie po stronie serwera. Zapytania POST w V2 wymagają też Content-Type: application/json. GET /api/v2/gender przyjmuje dodatkowo klucz w parametrze zapytania, ale nagłówki chronią dane uwierzytelniające przed ujawnieniem w adresach URL w przeglądarce. Brakujący, nieprawidłowo sformatowany lub nieznany klucz może skutkować użyciem wspólnej próby dla adresu IP; w integracji z kontem sprawdzaj, czy meta.access.mode ma wartość api_key. Znane klucze, które zostały wyłączone, wygasły lub mają ograniczenia, nie przełączają się na próbę.
Przeczytaj pełną odpowiedź →Jak obsługiwać limity zapytań i ponowne próby?V2 stosuje limity częstotliwości i równoczesnych zapytań; respektuj HTTP 429 i Retry-After. Każda powtórzona prognoza jest nową operacją, rozliczaną w zwykły sposób. Nie ponawiaj automatycznie zapytań po przekroczeniu limitu czasu, utracie odpowiedzi lub niepotwierdzonym rozliczeniu. Najpierw sprawdź code, action i meta.usage.billing_status; w przypadku billing_reconciliation_required skontaktuj się z pomocą techniczną, podając request_id. Ograniczonego wycofywania (backoff) używaj tylko wtedy, gdy rozliczenie jest potwierdzone, a udokumentowana akcja dopuszcza nową próbę.
Przeczytaj pełną odpowiedź →Jak interpretować błędy V2?Błędy API V2 używają kodów statusu HTTP oznaczających błąd oraz formatu Problem Details zgodnego z RFC 9457, ze stałymi polami code i action. Odczytuj te pola zamiast porównywać treść pola detail i zachowuj request_id na potrzeby pomocy technicznej. Pomyślny wynik bez prognozy nie jest błędem. Odpowiedź dla partii może zawierać błędy poszczególnych pozycji nawet przy HTTP 200. Serwer proxy może zwrócić błąd w formacie innym niż JSON, a utracona lub nieczytelna odpowiedź nie dowodzi, że nie pobrano kredytów.
Przeczytaj pełną odpowiedź →Jak sprawdzić pozostałe kredyty?Wywołaj GET /api/v2/usage z kluczem API w nagłówku Bearer w zaufanym kodzie po stronie serwera. To zapytanie jest bezpłatne i zwraca data.remaining_credits; bez klucza odczytuje wspólną próbę dla adresu IP. V1 i V2 korzystają z tego samego salda konta. Pole meta.usage w prognozie podaje opłatę za daną operację i saldo w chwili jej zakończenia, które może się zmieniać przy równoczesnych zapytaniach. Nie zapisuj danych uwierzytelniających w logach i nie traktuj odczytu salda jako dowodu, że konkretne zapytanie z utraconą odpowiedzią nie zostało rozliczone.
Przeczytaj pełną odpowiedź →Jak przejść z V1 na V2 bez przerywania działania integracji?Nowe integracje twórz w V2, a istniejących klientów V1 pozostaw na udokumentowanych ścieżkach, dopóki nie zdecydujesz się ich przenieść. Obie wersje korzystają z tych samych kluczy API i kredytów, ale mają różne pola zapytań, struktury odpowiedzi i formaty błędów. Postępuj zgodnie z przewodnikiem po migracji, przetestuj wyniki pomyślne, nieznane i błędy, a przed zmianą endpointu zaktualizuj kod analizujący odpowiedzi. Dokumentacja V1 pozostaje dostępna dla istniejących integracji.
Przeczytaj pełną odpowiedź →Jak diagnozować błędy i monitorować dostępność usługi?Jeśli zapytania kończą się niepowodzeniem, na podstawie zwróconego kodu błędu odróżnij awarię usługi od nieprawidłowych danych wejściowych, problemu z dostępem do konta, wyczerpanych kredytów lub limitów zapytań. Monitoruj odsetek udanych zapytań i opóźnienia we własnej integracji. W przypadku niewyjaśnionego błędu lub niepewnego rozliczenia skontaktuj się z pomocą techniczną, podając request_id. Twierdzenia o dostępności opieraj na wynikach pomiarów; to FAQ nie podaje gwarantowanego procentu dostępności.
Przeczytaj pełną odpowiedź →Nadal potrzebujesz pomocy?
Prześlij przykład pozwalający odtworzyć problem
Podaj endpoint, parametry zapytania i zwrócony błąd, ale nie udostępniaj produkcyjnego klucza API ani wrażliwych danych osobowych.