Chọn cách kết nối Integrately phù hợp với hợp đồng API
Các bước HTTP trong hướng dẫn này gọi GenderAPI.io V2 tại https://api.genderapi.io/api/v2/gender. Phần thân JSON gửi type và value. Kết quả ước tính nằm trong data, còn thông tin về yêu cầu và tính phí nằm trong meta. Trình kết nối gốc có hợp đồng riêng, được mô tả bên dưới.
Trang niêm yết GenderAPI.io trên Integrately liên kết đến genderapi.io và cung cấp các hành động cho tên, địa chỉ email và trích xuất tên từ địa chỉ email. Trang này không nêu phiên bản API bên dưới hay lược đồ đầu ra đầy đủ; chỉ riêng tên hành động không đủ để xác nhận khả năng tương thích với V2.
Integrately mô tả Webhook/API là một hành động POST gửi ra bên ngoài. Các tùy chọn header và trình soạn thảo JSON hiện tại của nó chưa được xác minh độc lập cho hướng dẫn này. Chỉ áp dụng đặc tả HTTP V2 bên dưới sau khi xác nhận rằng hành động của bạn có thể gửi header Authorization và phần thân JSON lồng nhau. Các hành động gốc hiện có vẫn giữ đặc tả trường riêng của chúng.
Chuẩn bị tài khoản và bản ghi nguồn
Ví dụ này bổ sung dữ liệu cho bản ghi Mailchimp dựa trên tên. Bạn cần quyền truy cập vào ứng dụng nguồn và ứng dụng đích, một khóa từ tài khoản GenderAPI.io và tính năng của nền tảng dùng cho hành động HTTP. Hướng dẫn này không kèm thông tin xác thực hợp lệ hay tài khoản đã kết nối.
V1 và V2 dùng chung khóa của tài khoản và cùng một số dư. Trước khi thiết lập một yêu cầu có tính phí, hãy xác minh khóa qua GET /api/v2/usage và kiểm tra rằng meta.access.mode là api_key trong phản hồi của endpoint này. Khóa bị thiếu hoặc không được nhận diện có thể chuyển sang chế độ dùng thử theo IP dùng chung; một quy trình tự động trong môi trường production không nên âm thầm phụ thuộc vào chế độ này.
Hãy tắt quy trình làm việc trong khi cấu hình. Một lần gửi ước tính để kiểm thử vẫn tiêu tốn tín dụng như bình thường. Các hướng dẫn này đã được đối chiếu với tài liệu công khai và đặc tả V2; chưa có quy trình nào được xác thực và chạy từ đầu đến cuối trên bất kỳ nền tảng nào cho lần xuất bản này.
Cấu hình yêu cầu GenderAPI.io V2 trong Integrately
- Chọn trình kích hoạt người đăng ký Mailchimp và kiểm tra một bản ghi kiểm thử. Lưu ID của audience và người đăng ký để cập nhật, chọn trường tên thực tế và bỏ qua các bản ghi không có tên.
- Tìm Webhook/API và hành động gửi dữ liệu đến một URL. Trước khi tiếp tục, hãy kiểm tra các thiết lập có sẵn: đặc tả dưới đây yêu cầu header có xác thực và phần thân JSON lồng nhau, nhưng các tùy chọn hiện tại của trình soạn thảo chưa được xác minh độc lập ở đây.
- Nếu hành động đáp ứng các yêu cầu đó, hãy chọn POST và endpoint V2 bên dưới. Dùng các thiết lập có sẵn trong tài khoản của bạn để yêu cầu gửi đi có Authorization: Bearer YOUR_API_KEY và Content-Type: application/json.
- Tạo phần thân JSON có type = name, options chứa ai_mode = off, và chỉ định value là tên đã ánh xạ. Hãy kiểm tra bản xem trước yêu cầu của hành động đã chọn. Ngay cả khi header Content-Type đã được đặt, payload biểu mẫu phẳng vẫn không phải là phần thân JSON của V2.
- Với tên động, hãy dùng tính năng ánh xạ hoặc tuần tự hóa JSON của nền tảng. Nếu hành động đã chọn không thể giữ JSON lồng nhau hoặc header có xác thực, hãy dùng một bước hỗ trợ HTTP thay vì đưa khóa hoặc JSON vào tham số truy vấn.
| Thiết lập HTTP | Giá trị | Mục đích |
|---|---|---|
Method | POST | Gửi một yêu cầu ước tính. |
URL | https://api.genderapi.io/api/v2/gender | Endpoint GenderAPI.io V2 cho một lần ước tính đơn lẻ. |
Authorization | Bearer YOUR_API_KEY | Thay giá trị giữ chỗ này trong phần cài đặt xác thực hoặc header của nền tảng. |
Content-Type | application/json | Gửi một đối tượng có đối tượng options lồng bên trong, không phải các trường biểu mẫu. |
options.ai_mode | off | Lần kiểm thử đầu tiên cố ý chỉ dùng tập dữ liệu. Mức tính phí thông thường là 1 tín dụng, kể cả với kết quả không xác định. |
Kiểm tra phần thân JSON trước khi gửi
Đây là ví dụ minh họa với đầu vào cố định, không phải kết quả ước tính. Trước tiên, hãy xác minh cấu trúc yêu cầu; sau đó thay value bằng trường nguồn đã ánh xạ, sử dụng cơ chế tuần tự hóa JSON đúng cách. Đừng gửi biểu thức ánh xạ của nền tảng đến API dưới dạng chuỗi nguyên văn.
Với loại đầu vào khác, hãy đặt type là name, email hoặc username và cung cấp value tương ứng. Chỉ thêm country khi có ngữ cảnh đáng tin cậy; trường này là tùy chọn và không phải là phép tra cứu quốc gia cư trú.
{
"type": "name",
"value": "Alice",
"options": {
"ai_mode": "off"
}
}Kiểm tra bước HTTP trước khi bật cập nhật
Trước khi chọn các trường ở bước sau, hãy chủ động kiểm thử hành động một lần và kiểm tra phần thân được trả về. Bước GenderAPI.io gốc và bước Webhook/API có thể hiển thị nhãn trường khác nhau, ngay cả khi khách hàng nguồn là như nhau.
Lưu khóa trong thiết lập kết nối hoặc xác thực yêu cầu dành cho mục đích đó, và giới hạn những người có thể xem hoặc chia sẻ quy trình tự động. Hướng dẫn công khai này không bao gồm khóa hoạt động được, kết nối đã xuất hay bước cập nhật khách hàng được cấu hình sẵn.
Xử lý riêng kết quả identified, kết quả không xác định và lỗi
Hãy phân tích phần thân phản hồi trước khi chọn cách cập nhật đích. Các đường dẫn JSON bên dưới trỏ đến phần thân V2; nền tảng của bạn có thể bọc hoặc làm phẳng phần thân này. Hãy xác nhận cấu trúc thực tế được trả về bằng một lần kiểm thử có chủ đích và gắn kết quả với ID của bản ghi nguồn.
Một ước tính không xác lập danh tính của một người hay giới tính do chính người đó tự công bố. Hãy lưu ước tính tách biệt với thông tin do người đó cung cấp. Chọn tiêu chí chấp nhận dựa trên dữ liệu đại diện cho khối lượng công việc của chính bạn, và đánh giá riêng độ tin cậy của tập dữ liệu và độ tin cậy của AI.
| Mục kiểm tra | Giá trị hoặc kiểu dự kiến | Quyết định trong quy trình |
|---|---|---|
meta.access.mode | api_key cho quy trình dùng tài khoản này | Dừng lại khi gặp ip_trial và sửa khóa. Một phản hồi thành công ở chế độ dùng thử theo IP không chứng minh tài khoản đã được xác thực và có thể đã tiêu tốn tín dụng dùng thử. |
meta.usage.billing_status | confirmed hoặc unconfirmed | Nếu là unconfirmed, hãy lưu ID yêu cầu và đối chiếu tính phí trước khi thử lại hoặc tiếp tục xử lý. |
data.result_status / data.gender | identified với male hoặc female; unknown với null | Lưu các kết quả identified đã được chấp nhận vào một trường riêng dành cho giá trị ước tính. Giữ nguyên các kết quả không xác định mà không gán danh mục mặc định. |
data.confidence / data.confidence_kind | số từ 0 đến 1 hoặc null; loại bằng chứng hoặc null | Diễn giải observed_frequency và model_reported một cách riêng biệt; không giá trị nào là bảo đảm độ chính xác chung. |
data.source / data.sample_count | dataset, ai hoặc none / số nguyên hoặc null | Lưu lại cách ước tính được tạo ra. AI không có số lượng mẫu được lưu trữ; số lượng mẫu của tập dữ liệu không phải là điểm độ chính xác của sản phẩm. |
meta.request_id / meta.usage | tham chiếu yêu cầu / đối tượng mức sử dụng | Lưu cả hai cùng với bản ghi quy trình và kết quả. Không ghi khóa API và dữ liệu cá nhân không cần thiết vào nhật ký thông thường. |
Lỗi HTTP / không có phản hồi | Problem Details hoặc không có phản hồi đầy đủ | Tạm dừng cập nhật và kiểm tra lỗi cùng trạng thái tính phí. Hết thời gian chờ không chứng minh rằng máy chủ chưa xử lý gì. |
Chỉ cập nhật bản ghi tương ứng trong Mailchimp
Dùng ID của audience và người đăng ký Mailchimp đã lưu để chọn bản ghi đích. Trước khi ghi vào một trường riêng dành cho giá trị ước tính hoặc thẻ đã được phê duyệt, hãy thêm điều kiện cho trạng thái kết quả và các bước kiểm tra quyền truy cập và tính phí ở trên. Đừng bao giờ chuyển giới tính bị thiếu hoặc null thành danh mục mặc định của liên hệ.
Trước khi bật cập nhật, hãy kiểm thử từng nhánh: kết quả identified, kết quả không xác định và lỗi. Phản hồi mẫu hư cấu cho phép kiểm tra điều kiện của nhánh mà không gửi yêu cầu ước tính mới. Việc cập nhật trong ứng dụng đích phải dựa trên các bước kiểm tra trên và không được ghi đè các trường hoặc thẻ không liên quan.
Kiểm soát việc thử lại và tính phí trùng lặp
Integrately mô tả cơ chế tự động thử lại, bao gồm cả các thiết lập áp dụng cho toàn công ty. Trước khi bật quy trình tự động này, hãy kiểm tra chính sách và lịch sử tác vụ, đồng thời đánh giá ảnh hưởng đến các quy trình khác trước khi thay đổi một thiết lập dùng chung. Mỗi yêu cầu HTTP lặp lại là một yêu cầu độc lập có tính phí; hãy lưu đầu ra thành công để có thể sửa lỗi Mailchimp ở bước sau mà không cần gửi lại yêu cầu.
Mỗi yêu cầu mới tới GenderAPI là một thao tác độc lập. Trước khi gửi, hãy loại bỏ các sự kiện nguồn bị lặp lại trong quy trình bằng ID nguồn và trạng thái xử lý đã lưu. ID của bản ghi nguồn không phải là khóa chống trùng lặp phía máy chủ.
Kết quả không xác định thành công là một kết quả đã hoàn tất và có tính phí. Khi hết thời gian chờ hoặc phản hồi không đầy đủ, bạn có thể không biết cả kết quả lẫn việc tính phí. Hãy lưu thông tin tham chiếu của yêu cầu nếu có và kiểm tra việc tính phí trước khi gửi lại yêu cầu. Nếu phản hồi giới hạn tốc độ có header Retry-After, hãy tuân theo header đó.
Chọn khi nào dùng AI
forceToGenderize là tùy chọn cho tên, địa chỉ email và tên người dùng. Khi bật trường này, hãy bỏ qua ai_mode hoặc dùng fallback; off và always xung đột với nó và trả về 422. Chỉ cần số dư ban đầu dương là đủ để bắt đầu một yêu cầu, kể cả khi lần tính phí cuối cùng làm số dư xuống dưới 0.
Chế độ biệt danh có thể trả về giới tính cùng name: null. Chế độ này cũng có thể trả về kết quả không xác định. Cả AI dự phòng thông thường lẫn suy luận biệt danh đều không bảo đảm câu trả lời đúng hoặc khác null.
| Tùy chọn yêu cầu | Cách hoạt động | Tín dụng cho một lần tra cứu thành công |
|---|---|---|
| options.ai_mode: off | Chỉ dùng tập dữ liệu. | 1, kể cả kết quả không xác định |
| options.ai_mode: fallback | Tra tập dữ liệu trước, sau đó dùng AI thông thường khi không có giới tính được trả về. Đây là mặc định cho yêu cầu đơn lẻ. | Tổng cộng 1, đã gồm AI dự phòng |
| options.ai_mode: always | Dùng AI trực tiếp. | 2 |
| forceToGenderize: true | Tra tập dữ liệu trước, sau đó cho phép AI diễn giải biệt danh cá nhân hoặc bí danh, kể cả khi không có tên thật. | 1 khi tập dữ liệu cho ra kết quả; tổng cộng 2 nếu dùng AI |
Xác minh quy trình trước khi tăng khối lượng
- Bằng một lần kiểm thử có chủ đích, hãy xác minh JSON thực tế đã được tuần tự hóa, các đường dẫn kết quả đã phân tích, quyền truy cập bằng khóa API và việc tính phí đã được xác nhận. Khi có thể, hãy kiểm thử cách xử lý kết quả không xác định và lỗi bằng các phản hồi mẫu.
- Xác định rõ bước nào của quy trình sẽ được thử lại và trường nào của khách hàng sẽ thay đổi. Hãy lưu ID của bản ghi nguồn, phản hồi đã nhận và tham chiếu yêu cầu để nếu bước cập nhật đích thất bại sau đó, bạn không cần gửi lại yêu cầu.
- Trước tiên, hãy bật một lần chạy nhỏ có kiểm soát và kiểm tra các bản ghi cùng lượng tín dụng đã dùng trước khi tăng mức xử lý song song. Tín dụng GenderAPI và chi phí tác vụ hoặc thao tác do nền tảng tự động hóa tính là hai khoản riêng biệt.
- Với yêu cầu hàng loạt, hãy dùng POST /api/v2/gender/batch với tối đa 50 mục khi truy cập bằng khóa API hoặc 10 mục khi dùng thử theo IP. Mảng items có thể kết hợp tên, địa chỉ email và tên người dùng, với tùy chọn rõ ràng và id duy nhất cho từng mục. Hãy kiểm tra từng kết quả; phản hồi HTTP 200 vẫn có thể chứa lỗi của từng mục. Việc trình kết nối gốc có hỗ trợ yêu cầu hàng loạt hay không cần được kiểm tra riêng.
Câu hỏi thường gặp
Tôi có thể ánh xạ trường probability của hành động gốc cũ sang confidence của V2 không?
Trước tiên, hãy xem lại đặc tả phản hồi. Khi gọi trực tiếp V2, data.confidence được trả về cùng data.confidence_kind theo thang từ 0 đến 1 hoặc null. Không nên mặc định rằng nhãn trường và thang đo của trình kết nối gốc khớp với các đường dẫn này.
Ví dụ gọi HTTP trực tiếp có sử dụng AI không?
Phần thân của yêu cầu đầu tiên đặt options.ai_mode là off. Hãy chủ động đổi giá trị này thành fallback nếu muốn dùng AI dự phòng thông thường (tổng cộng 1 tín dụng), hoặc thành always nếu muốn dùng AI trực tiếp (2 tín dụng). forceToGenderize thử tập dữ liệu trước: tốn 1 tín dụng nếu được giải quyết tại đó, hoặc tổng cộng 2 tín dụng khi AI được sử dụng.
Kết quả không xác định có miễn phí không, và có an toàn để tự động gửi lại không?
Không. Một kết quả không xác định thành công là kết quả hoàn chỉnh và bị tính phí. Một lần thử lại là một lần tra cứu mới. Với lỗi truyền tải hoặc tính phí chưa được xác nhận, hãy kiểm tra dữ liệu mức sử dụng được trả về và tham chiếu yêu cầu trước khi quyết định có gửi lại hay không.
Quy trình này đã được chạy trên một tài khoản đã kết nối chưa?
Chưa. Hướng dẫn thiết lập cho từng nền tảng đã được đối chiếu với tài liệu công khai vào ngày 26 tháng 9, 2026. Phần giải thích về yêu cầu và phản hồi của GenderAPI.io V2 đã được rà soát vào ngày 27 tháng 9, 2026. Lần rà soát bản tiếng Việt này vào ngày 29 tháng 9, 2026 là bước kiểm tra bản dịch, không phải một lần kiểm thử mới bằng tài khoản. Trước khi bật cập nhật trong môi trường production, hãy kiểm thử bằng tài khoản của chính bạn các trường hiện tại của hành động đã chọn, xác thực, phần thân yêu cầu, phản hồi và cách thử lại.
Nguồn và tài liệu
Phiên bản tiếng Việt được kiểm tra lần cuối vào ngày . Thông tin về các nền tảng dựa trên tài liệu công khai của họ, được kiểm tra vào ngày 26 tháng 9, 2026. Lần kiểm tra này không phải là một bài kiểm thử mới với tài khoản đã kết nối. Hãy xem cấu hình và tình trạng cung cấp hiện tại trong tài liệu chính thức của từng nền tảng.