将 Zapier 连接到 GenderAPI.io V2

准备账户和源记录

本示例根据电子邮箱地址为 Mailchimp 记录补充数据。您需要能够访问源应用和目标应用，拥有一个 GenderAPI.io 账户密钥，并具备 HTTP 操作所需的平台功能。本指南不包含有效的凭据或已连接的账户。

V1 和 V2 使用相同的账户密钥和相同的余额。在配置付费请求之前，请先用 GET /api/v2/usage 检查密钥，并确认该端点响应中的 meta.access.mode 为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。生产环境中的自动化不应在您不知情的情况下依赖这种情况。

配置期间请保持工作流处于关闭状态。一次测试预测会正常消耗积分。本文说明依据各平台的公开文档和 V2 契约审核而成。为撰写本文，没有在任何平台上端到端运行过经过身份验证的工作流。

• 身份验证与免费用量检查 →

在 Zapier 中配置 GenderAPI.io V2 请求

• 从能够提供正确订阅者记录的 Mailchimp 触发器开始。保存受众（Audience）ID 和联系人 ID，并在 HTTP 操作之前添加一个过滤器，跳过电子邮箱地址为空的记录。
• 选择 Webhooks by Zapier 和 POST 操作。填写下方的 URL，并选择 Payload Type: JSON。添加数据字段 type = email、value = 映射后的订阅者电子邮箱地址，以及 options__ai_mode = off。
• 在 Zapier 中，双下划线写法 options__ai_mode 会在 JSON 请求体中嵌套为 options.ai_mode。下方代码块展示的是 API 实际收到的请求体，并不是需要您在操作中添加的第四个字段。
• 在 Headers 部分添加 Authorization，值为 Bearer YOUR_API_KEY。Content-Type 使用 application/json。不要把密钥写进触发器字段、查询字符串或示例响应中。

发送前检查 JSON 请求体

示例展示的是一个固定输入，并不是预期结果。请先检查请求结构，然后用正确的 JSON 序列化方式把 value 替换为映射后的源字段。不要把平台的映射表达式作为字面文本发送给 API。

对于其他输入，请把 type 设置为 name、email 或 username，并在 value 中提供相应的值。只有在您掌握可靠的背景信息时才添加 country。该字段是可选的，不能用来确定一个人居住在哪个国家/地区。

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

• 请求字段、类型与默认值 →

启用更新之前先检查 HTTP 步骤

Webhook 请求头并不是专门存放机密信息的字段：任何能够编辑该 Zap 的人都能看到它们。请限制访问权限，不要分享包含凭据的 Zap、截图或导出文件。Zapier 还提供带有已保存凭据的 API by Zapier，但它的请求体配置方式与这里的结构化 POST 方案不同。

不要封装请求体：只发送一个对象，而不是列表或数组。对于映射的客户数据，请选择结构化 JSON 操作。Custom Request 发送的是原始文本，不会自动转义插入值中的特殊字符。

• Zapier 中的结构化 Webhook 请求与嵌套 JSON →
• API by Zapier 中的凭据连接 →
• Zapier 中重放（Replay）的工作方式 →

分别处理 identified、unknown 和错误

在选择目标系统中的更新操作之前，请先解析响应体。下表中的 JSON 路径指的是 V2 响应体。您的平台可能会对其进行封装或展平。请通过一次有限的测试检查实际返回的结构，并把结果与源记录 ID 一起保存。

预测结果不能确定一个人的身份，也不能确定其本人自述的性别。请把它与本人提供的信息分开保存。请用代表您使用场景的数据制定验收标准，并分别评估数据集置信度和 AI 置信度。

• 完整的 V2 响应参考 →
• 错误、超时与重试决策 →

只更新 Mailchimp 中对应的记录

检查测试操作解析后的响应，并为 data.gender、data.result_status 以及上文列出的其他 V2 路径选择字段。Zapier 的字段选择器可能会展平嵌套的标签：请以观察到的值和顶层路径为准，而不要默认使用原生连接器旧的 probability 字段。只更新已保存 ID 的那位 Mailchimp 订阅者。

在启用更新之前，请分别测试 identified 结果、unknown 结果和错误这三条分支。使用虚构的示例响应，可以在不发送新预测的情况下检查分支条件。目标应用中的更新必须依赖上述检查，并且不得覆盖与之无关的字段或标签。

• 响应字段与未知结果 →
• 准确性与置信度说明 →
• 数据来源与注明日期的数据库概况 →

控制重试和重复计费

在启用 Zap 之前，请检查 Zapier 中的 Autoreplay 和手动重放（Replay）设置。如果重放一个失败的 Webhook 操作，就会发送一次新的请求。不要仅仅为了修正后续的 Mailchimp 步骤而重放已完成的请求。请把原始订阅者 ID 和请求结果一起保存。

每一次新的 GenderAPI 请求都是一次独立的操作。请在发送之前，利用已保存的源 ID 和处理状态，在工作流中对重复的源事件进行去重。源记录 ID 并不是服务器端防止重复的键。

已完成的 unknown 结果是一个完整且计费的结果。如果出现超时或响应不完整，结果和计费情况都可能未知：如果有请求引用，请保存它，并在重新发送请求之前核实计费情况。当请求频率超限的响应带有 Retry-After 响应头时，请遵守该值。

• 积分与计费状态 →

决定何时使用 AI

forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。

昵称模式可能在 name: null 的同时返回性别，也可能得到未知结果。无论是普通的 AI 回退还是昵称解读，都不能保证答案正确或返回非 null 的值。

• AI 选项与昵称解读 →
• 积分与用量 →

扩大处理量之前先检查工作流

• 通过一次有限的测试，检查实际序列化后的 JSON、解析出的结果路径、API 密钥访问以及计费确认。如果可能，请用示例响应测试 unknown 结果和错误的处理方式。
• 明确工作流中哪些步骤会重复执行，以及会修改哪些客户字段。保存源记录 ID、收到的响应和请求引用，这样目标系统稍后出现故障时就不需要再发送一次请求。
• 先启用一次小规模的受控运行，检查记录和积分后再提高并发。GenderAPI 积分与自动化平台按任务或操作收取的费用是两笔独立的费用。
• 对于批量处理，请使用 POST /api/v2/gender/batch：使用 API 密钥访问时最多 50 个条目，使用 IP 试用时最多 10 个。items 数组可以混合包含姓名、电子邮箱地址和用户名，每个条目都带有明确的选项和唯一的 ID。请逐一检查每个结果：HTTP 200 响应中也可能包含单个条目的错误。原生连接器是否支持批量处理，需要另行核实。

• 批量请求与单个条目的错误 →
• Python 实施指南 →
• Node.js 实施指南 →

常见问题