# Kết nối Pipedream với GenderAPI.io V2

> Kết nối Pipedream với GenderAPI.io V2 cho bản ghi Twilio SendGrid: chọn đúng trình kết nối, gửi type và value, rồi xử lý data, meta, tín dụng và lỗi.

Canonical HTML: https://www.genderapi.io/vi/blog/pipedream-gender-api-integration

Last reviewed: 2026-09-29

## Chọn cách kết nối Pipedream 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.

Thành phần GenderAPI.io công khai của Pipedream, được rà soát ngày 26 tháng 9, 2026, dùng URL gốc cũ https://api.genderapi.io/api và gửi name hoặc email, country tùy chọn cùng khóa API dưới dạng tham số truy vấn. Bản triển khai đã công bố này là trình kết nối V1, không phải endpoint JSON của V2.

Bạn có thể tiếp tục dùng hành động gốc hiện có theo đặc tả riêng của nó, hoặc thêm một bước HTTP chung cho V2. Đừng mặc định rằng cơ chế xác thực tự động của tài khoản đã kết nối qua ứng dụng gốc cũng phù hợp với yêu cầu V2 riêng biệt này: cấu hình này dùng rõ ràng một header Bearer.

- [Trang niêm yết chính thức của ứng dụng GenderAPI.io trên Pipedream](https://pipedream.com/apps/genderapi-io)
- [Tài liệu V1 hiện có](https://www.genderapi.io/vi/api-documentation/v1)

## 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 Twilio SendGrid dựa trên địa chỉ email. 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.

- [Xác thực và kiểm tra mức sử dụng miễn phí](https://www.genderapi.io/vi/docs/v2/authentication#environment-setup)

## Cấu hình yêu cầu GenderAPI.io V2 trong Pipedream

- Chọn sự kiện hoặc lịch chạy Twilio SendGrid phù hợp với tài khoản và quy trình của bạn. Kiểm tra một liên hệ kiểm thử, lưu ID cố định của liên hệ đó và bỏ qua các địa chỉ email trống trước bước bổ sung dữ liệu. Khoảng thời gian khả dụng của trình kích hoạt là thiết lập của nền tảng, không phải cam kết của GenderAPI.
- Thêm hành động "Send any HTTP Request", chọn POST và nhập URL bên dưới. Cấu hình phần thân JSON với type = email, options.ai_mode = off, và chỉ định value là địa chỉ email của liên hệ.
- Hãy lưu khóa bằng tính năng thông tin xác thực hoặc biến môi trường của Pipedream. Đặt Authorization là Bearer theo sau là giá trị bí mật đó, và đặt Content-Type là application/json. Đừng tiếp tục dùng cơ chế xác thực gốc đặt khóa trong chuỗi truy vấn, và đừng in khóa ra trong một bước.
- Tạo phần thân dưới dạng đối tượng JSON bằng các tính năng ánh xạ mà hành động hỗ trợ. Tránh tự ghép JSON thô bằng cách nối các giá trị liên hệ chưa được thoát ký tự. Hãy kiểm tra bản xem trước của yêu cầu trước khi chủ động chạy một lần kiểm thử.

| 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ú.

**Yêu cầu JSON V2 cho Pipedream**

```json
{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}
```

- [Tất cả trường, kiểu và giá trị mặc định của yêu cầu](https://www.genderapi.io/vi/docs/v2/request-parameters)

## Kiểm tra bước HTTP trước khi bật cập nhật

Kiểm tra phản hồi do bước HTTP xuất ra và tìm phần thân đã phân tích. Nếu hành động bạn chọn trả về phần thân dưới dạng văn bản, hãy phân tích nó một lần trước khi đọc data và meta. Trường data của lớp bọc truyền tải khác với trường data trong phần thân V2.

Với quy trình dựa trên mã có kiểm soát rõ ràng về hết thời gian chờ, chuyển hướng và thử lại, hãy dùng hướng dẫn Node.js đã được kiểm thử được liên kết bên dưới. Hành động chung và ứng dụng gốc có thể có thiết lập truyền tải mặc định khác nhau.

- [Thành phần GenderAPI.io công khai của Pipedream](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs)
- [Hành động yêu cầu HTTP của Pipedream](https://pipedream.com/docs/workflows/building-workflows/http)
- [Biến môi trường bí mật của Pipedream](https://pipedream.com/docs/workflows/environment-variables)
- [Thiết lập quy trình và thử lại trên Pipedream](https://pipedream.com/docs/workflows/building-workflows/settings)

## 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ì. |

- [Tài liệu tham khảo đầy đủ về phản hồi V2](https://www.genderapi.io/vi/docs/v2/responses)
- [Quyết định khi gặp lỗi, hết thời gian chờ và thử lại](https://www.genderapi.io/vi/docs/v2/errors-and-retries)

## Chỉ cập nhật bản ghi tương ứng trong Twilio SendGrid

Lưu ID liên hệ do trình kích hoạt trả về cùng với phần thân V2 đã phân tích. Sau khi áp dụng các bước kiểm tra kết quả ở trên, chỉ cập nhật các trường tùy chỉnh SendGrid mong muốn. Giữ nguyên tên do liên hệ cung cấp; data.name suy ra từ địa chỉ email là một ứng viên được suy luận, không phải giá trị thay thế đã được xác minh.

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.

- [Trường phản hồi và kết quả không xác định](https://www.genderapi.io/vi/docs/v2/responses)
- [Giải thích về độ chính xác và độ tin cậy](https://www.genderapi.io/vi/accuracy-methodology)
- [Nguồn dữ liệu và hồ sơ tập dữ liệu có ghi ngày](https://www.genderapi.io/vi/data-provenance)

## Kiểm soát việc thử lại và tính phí trùng lặp

Pipedream mô tả cơ chế tự động thử lại từ bước thất bại, tùy thuộc vào gói dịch vụ. Hãy xem lại các thiết lập đó và mọi cơ chế thử lại trong hành động HTTP đã chọn. Việc thử lại bước bổ sung dữ liệu có thể bị tính phí thêm lần nữa; lỗi ở đích phía sau nên được sửa bằng đầu ra bổ sung dữ liệu đã lư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 đó.

- [Tín dụng và trạng thái tính phí](https://www.genderapi.io/vi/docs/v2/credits-and-usage)

## 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 |

- [Tùy chọn AI và suy luận biệt danh](https://www.genderapi.io/vi/docs/v2/ai-options)
- [Tín dụng và mức sử dụng](https://www.genderapi.io/vi/docs/v2/credits-and-usage)

## 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.

- [Yêu cầu hàng loạt và lỗi của từng mục](https://www.genderapi.io/vi/docs/v2/batch)
- [Hướng dẫn triển khai bằng Python](https://www.genderapi.io/vi/integrations/python)
- [Hướng dẫn triển khai bằng Node.js](https://www.genderapi.io/vi/integrations/javascript)

## Hành động GenderAPI.io gốc của Pipedream có dùng V2 không?

Thành phần công khai được rà soát ngày 26 tháng 9, 2026 dùng các endpoint V1 cũ và cơ chế xác thực đặt khóa trong chuỗi truy vấn. Với yêu cầu V2, hãy dùng cấu hình HTTP rõ ràng dành cho V2, và kiểm tra lại nếu phiên bản của thành phần đã công bố thay đổi.

## 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

- [Ứng dụng GenderAPI.io trên Pipedream](https://pipedream.com/apps/genderapi-io)
- [Thành phần GenderAPI.io công khai của Pipedream](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs)
- [Hành động yêu cầu HTTP của Pipedream](https://pipedream.com/docs/workflows/building-workflows/http)
- [Biến môi trường bí mật của Pipedream](https://pipedream.com/docs/workflows/environment-variables)
- [Thiết lập quy trình và thử lại trên Pipedream](https://pipedream.com/docs/workflows/building-workflows/settings)
- [Đặc tả yêu cầu của GenderAPI.io V2](https://www.genderapi.io/vi/docs/v2/request-parameters)
- [Đặc tả phản hồi của GenderAPI.io V2](https://www.genderapi.io/vi/docs/v2/responses)
- [Tính phí và tín dụng của GenderAPI.io V2](https://www.genderapi.io/vi/docs/v2/credits-and-usage)