选择与您的 API 契约相匹配的 Pipedream 连接方式
本指南中的 HTTP 方案调用位于 https://api.genderapi.io/api/v2/gender 的 GenderAPI.io V2。请在 JSON 请求体中发送 type 和 value。预测结果位于 data 中，请求和计费信息位于 meta 中。原生连接器有各自的契约，详见下文。
2026年9月26日审核的 Pipedream 公开 GenderAPI.io 组件使用旧的基础地址 https://api.genderapi.io/api，并把 name 或 email、可选的 country 以及 API 密钥作为查询字符串参数发送。已发布的实现是一个 V1 连接器，而不是 V2 的 JSON 端点。
您可以按原有契约继续使用现有的原生操作，也可以为 V2 添加一个通用的 HTTP 步骤。不要以为原生连接账户的自动身份验证也适用于这个独立的 V2 请求：本方案明确使用 Bearer 请求头。
准备账户和源记录
本示例根据电子邮箱地址为 Twilio SendGrid 记录补充数据。您需要能够访问源应用和目标应用，拥有一个 GenderAPI.io 账户密钥，并具备 HTTP 操作所需的平台功能。本指南不包含有效的凭据或已连接的账户。
V1 和 V2 使用相同的账户密钥和相同的余额。在配置付费请求之前，请先用 GET /api/v2/usage 检查密钥，并确认该端点响应中的 meta.access.mode 为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。生产环境中的自动化不应在您不知情的情况下依赖这种情况。
配置期间请保持工作流处于关闭状态。一次测试预测会正常消耗积分。本文说明依据各平台的公开文档和 V2 契约审核而成。为撰写本文，没有在任何平台上端到端运行过经过身份验证的工作流。
在 Pipedream 中配置 GenderAPI.io V2 请求
- 选择适合您账户和工作流的 Twilio SendGrid 事件或定时计划。检查一个测试联系人，保存其稳定的 ID，并在补充数据步骤之前跳过电子邮箱地址为空的记录。触发器可用的时间间隔是平台的设置，而不是 GenderAPI 的承诺。
- 添加 Send any HTTP Request 操作，选择 POST 并填写下方的 URL。配置 JSON 请求体：type = email、value = 联系人的电子邮箱地址、options.ai_mode = off。
- 使用 Pipedream 的凭据或环境变量控件保存密钥。把 Authorization 设置为 Bearer 加上该机密值，把 Content-Type 设置为 application/json。不要继续使用把密钥放在查询字符串中的原生身份验证方式，也不要在任何步骤中显示密钥。
- 使用该操作支持的映射控件，把请求体创建为一个 JSON 对象。不要在未转义特殊字符的情况下拼接联系人的值来生成原始 JSON。运行有限的测试之前，请先检查请求预览。
| HTTP 设置 | 值 | 用途 |
|---|---|---|
Method | POST | 发送一次预测请求。 |
URL | https://api.genderapi.io/api/v2/gender | 用于单个预测的 GenderAPI.io V2 端点。 |
Authorization | Bearer YOUR_API_KEY | 在平台的身份验证或请求头设置中替换这个占位符。 |
Content-Type | application/json | 发送一个包含嵌套 options 对象的对象，而不是表单字段。 |
options.ai_mode | off | 第一次有意只使用数据集进行的测试：正常计费 1 个积分，即使结果为 unknown 也是如此。 |
发送前检查 JSON 请求体
示例展示的是一个固定输入，并不是预期结果。请先检查请求结构，然后用正确的 JSON 序列化方式把 value 替换为映射后的源字段。不要把平台的映射表达式作为字面文本发送给 API。
对于其他输入，请把 type 设置为 name、email 或 username，并在 value 中提供相应的值。只有在您掌握可靠的背景信息时才添加 country。该字段是可选的，不能用来确定一个人居住在哪个国家/地区。
{
"type": "email",
"value": "alex@example.com",
"options": {
"ai_mode": "off"
}
}启用更新之前先检查 HTTP 步骤
检查 HTTP 步骤导出的响应，并找到解析后的响应体。如果所选操作以文本形式返回响应体，请先解析一次，再读取 data 和 meta。传输封装中的 data 字段与 V2 响应体中的 data 字段并不相同。
如果您需要一个基于代码、可以明确控制超时、重定向和重试的工作流，可以使用下方经过测试的 Node.js 指南。通用操作和原生应用可能有不同的默认传输设置。
分别处理 identified、unknown 和错误
在选择目标系统中的更新操作之前，请先解析响应体。下表中的 JSON 路径指的是 V2 响应体。您的平台可能会对其进行封装或展平。请通过一次有限的测试检查实际返回的结构，并把结果与源记录 ID 一起保存。
预测结果不能确定一个人的身份，也不能确定其本人自述的性别。请把它与本人提供的信息分开保存。请用代表您使用场景的数据制定验收标准，并分别评估数据集置信度和 AI 置信度。
| 检查项 | 预期值或类型 | 工作流中的决策 |
|---|---|---|
meta.access.mode | 对于使用账户的工作流，应为 api_key | 如果值为 ip_trial，请停止工作流并修正密钥。通过 IP 试用获得的成功响应并不能证明账户已通过身份验证，而且可能已经消耗了试用积分。 |
meta.usage.billing_status | confirmed 或 unconfirmed | 如果值为 unconfirmed，请保存请求 ID，并在重试或继续之前核实计费情况。 |
data.result_status / data.gender | identified 时为 male 或 female；unknown 时为 null | 把已接受的 identified 结果保存到专门存放推断数据的字段中。保留 unknown 结果，不要为其指定默认类别。 |
data.confidence / data.confidence_kind | 0 到 1 之间的数值或 null；依据类型或 null | 分别解读 observed_frequency 和 model_reported。这两个值都不能保证整体准确率。 |
data.source / data.sample_count | dataset、ai 或 none / 整数或 null | 保存预测的来源。AI 没有存储的样本数，数据集的样本数也不是衡量产品准确率的指标。 |
meta.request_id / meta.usage | 请求引用 / 用量对象 | 把两者与工作流记录和结果一起保存。不要把 API 密钥或不必要的个人数据写入常规日志。 |
HTTP 错误 / 没有响应 | Problem Details 或没有完整响应 | 暂停更新，并检查错误和计费状态。超时并不能证明服务器没有做任何处理。 |
只更新 Twilio SendGrid 中对应的记录
把触发器返回的联系人 ID 与解析后的 V2 响应体一起保存。在完成上述结果检查之后，只更新 SendGrid 中计划好的自定义字段。保留联系人本人提供的姓名：从电子邮箱地址推断出的 data.name 只是一个推断出的候选值，而不是经过确认的替代值。
在启用更新之前，请分别测试 identified 结果、unknown 结果和错误这三条分支。使用虚构的示例响应，可以在不发送新预测的情况下检查分支条件。目标应用中的更新必须依赖上述检查，并且不得覆盖与之无关的字段或标签。
控制重试和重复计费
Pipedream 的文档说明，根据方案不同，可以从失败的步骤开始自动重试。请检查这些设置以及所选 HTTP 操作的重试行为。对失败的补充数据步骤进行重试可能会产生新的费用。目标系统后续出现的故障应使用已保存的补充数据输出来修正。
每一次新的 GenderAPI 请求都是一次独立的操作。请在发送之前，利用已保存的源 ID 和处理状态，在工作流中对重复的源事件进行去重。源记录 ID 并不是服务器端防止重复的键。
已完成的 unknown 结果是一个完整且计费的结果。如果出现超时或响应不完整，结果和计费情况都可能未知：如果有请求引用，请保存它，并在重新发送请求之前核实计费情况。当请求频率超限的响应带有 Retry-After 响应头时，请遵守该值。
决定何时使用 AI
forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。
昵称模式可能在 name: null 的同时返回性别，也可能得到未知结果。无论是普通的 AI 回退还是昵称解读，都不能保证答案正确或返回非 null 的值。
| 请求选项 | 行为 | 每次成功查询消耗的积分 |
|---|---|---|
| options.ai_mode: off | 仅使用数据集。 | 1，未知结果也是如此 |
| options.ai_mode: fallback | 先查询数据集；如果没有返回性别，再使用普通的 AI。这是单个请求的默认值。 | 总共 1，包括 AI 回退 |
| options.ai_mode: always | 直接使用 AI。 | 2 |
| forceToGenderize: true | 先查询数据集，然后允许 AI 解读个人昵称或别名，即使没有真实名字也可以。 | 数据集得出结果时为 1；使用 AI 时总共为 2 |
扩大处理量之前先检查工作流
- 通过一次有限的测试，检查实际序列化后的 JSON、解析出的结果路径、API 密钥访问以及计费确认。如果可能，请用示例响应测试 unknown 结果和错误的处理方式。
- 明确工作流中哪些步骤会重复执行，以及会修改哪些客户字段。保存源记录 ID、收到的响应和请求引用，这样目标系统稍后出现故障时就不需要再发送一次请求。
- 先启用一次小规模的受控运行，检查记录和积分后再提高并发。GenderAPI 积分与自动化平台按任务或操作收取的费用是两笔独立的费用。
- 对于批量处理，请使用 POST /api/v2/gender/batch：使用 API 密钥访问时最多 50 个条目，使用 IP 试用时最多 10 个。items 数组可以混合包含姓名、电子邮箱地址和用户名，每个条目都带有明确的选项和唯一的 ID。请逐一检查每个结果：HTTP 200 响应中也可能包含单个条目的错误。原生连接器是否支持批量处理，需要另行核实。
常见问题
Pipedream 中的原生 GenderAPI.io 操作使用 V2 吗？
2026年9月26日审核的公开组件使用旧的 V1 端点，并通过查询字符串中的密钥进行身份验证。如需发送 V2 请求，请使用明确的 V2 HTTP 方案；如果已发布组件的版本发生变化，请重新检查。
直接 HTTP 示例会使用 AI 吗？
第一个请求的请求体把 options.ai_mode 设置为 off。如需使用普通的自动 AI 回退，请有意地把该值改为 fallback，总共消耗 1 个积分；如需直接使用 AI，请改为 always，消耗 2 个积分。forceToGenderize 会先查询数据集：如果在数据集中得出结果，消耗 1 个积分；如果使用了 AI，总共消耗 2 个积分。
unknown 结果是免费的吗？可以安全地自动重试吗？
不是。已完成的 unknown 结果是一个完整且计费的结果。每次重试都是一次新的查询。如果出现传输错误或计费未确认，请先检查返回的用量数据和请求引用，再决定是否重新发送请求。
这个工作流是否已用已连接的账户运行过？
没有。平台配置说明于 2026年9月26日依据各平台的公开文档审核。GenderAPI.io V2 请求和响应的说明于 2026年9月27日审核。本中文版于 2026年9月29日进行的审核是对翻译的核对，并不是用账户进行的新测试。在启用生产环境中的更新之前，请用您自己的账户核实所选操作当前的字段、身份验证、请求体、响应和重试行为。
来源与文档
中文版最近一次审核于 。各平台的相关信息依据其公开文档，审核日期为 2026年9月26日。此次审核并不是用已连接的账户进行的新测试。请在各平台的官方文档中确认当前的配置方式和可用性。