# 将 Pipedream 连接到 GenderAPI.io V2 > 为 Twilio SendGrid 记录将 Pipedream 连接到 GenderAPI.io V2。选择合适的连接器，发送 type 和 value，然后处理 data、meta、积分和错误。 Canonical HTML: https://www.genderapi.io/zh/blog/%E5%B0%86-gender-api-%E4%B8%8E-pipedream-%E9%9B%86%E6%88%90%E7%9A%84%E5%88%86%E6%AD%A5%E6%8C%87%E5%8D%97 Last reviewed: 2026-09-29 ## 选择与您的 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 请求头。 - [Pipedream 上的 GenderAPI.io 应用](https://pipedream.com/apps/genderapi-io) - [现有的 V1 文档](https://www.genderapi.io/zh/api-documentation/v1) ## 准备账户和源记录 本示例根据电子邮箱地址为 Twilio SendGrid 记录补充数据。您需要能够访问源应用和目标应用，拥有一个 GenderAPI.io 账户密钥，并具备 HTTP 操作所需的平台功能。本指南不包含有效的凭据或已连接的账户。 V1 和 V2 使用相同的账户密钥和相同的余额。在配置付费请求之前，请先用 GET /api/v2/usage 检查密钥，并确认该端点响应中的 meta.access.mode 为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。生产环境中的自动化不应在您不知情的情况下依赖这种情况。 配置期间请保持工作流处于关闭状态。一次测试预测会正常消耗积分。本文说明依据各平台的公开文档和 V2 契约审核而成。为撰写本文，没有在任何平台上端到端运行过经过身份验证的工作流。 - [身份验证与免费用量检查](https://www.genderapi.io/zh/docs/v2/authentication#environment-setup) ## 在 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。该字段是可选的，不能用来确定一个人居住在哪个国家/地区。 **Pipedream 的 V2 JSON 请求** ```json { "type": "email", "value": "alex@example.com", "options": { "ai_mode": "off" } } ``` - [请求字段、类型与默认值](https://www.genderapi.io/zh/docs/v2/request-parameters) ## 启用更新之前先检查 HTTP 步骤 检查 HTTP 步骤导出的响应，并找到解析后的响应体。如果所选操作以文本形式返回响应体，请先解析一次，再读取 data 和 meta。传输封装中的 data 字段与 V2 响应体中的 data 字段并不相同。 如果您需要一个基于代码、可以明确控制超时、重定向和重试的工作流，可以使用下方经过测试的 Node.js 指南。通用操作和原生应用可能有不同的默认传输设置。 - [Pipedream 公开的 GenderAPI.io 组件](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs) - [Pipedream 中的 HTTP 请求操作](https://pipedream.com/docs/workflows/building-workflows/http) - [Pipedream 中的机密环境变量](https://pipedream.com/docs/workflows/environment-variables) - [Pipedream 中的工作流设置与重试](https://pipedream.com/docs/workflows/building-workflows/settings) ## 分别处理 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 或没有完整响应 | 暂停更新，并检查错误和计费状态。超时并不能证明服务器没有做任何处理。 | - [完整的 V2 响应参考](https://www.genderapi.io/zh/docs/v2/responses) - [错误、超时与重试决策](https://www.genderapi.io/zh/docs/v2/errors-and-retries) ## 只更新 Twilio SendGrid 中对应的记录 把触发器返回的联系人 ID 与解析后的 V2 响应体一起保存。在完成上述结果检查之后，只更新 SendGrid 中计划好的自定义字段。保留联系人本人提供的姓名：从电子邮箱地址推断出的 data.name 只是一个推断出的候选值，而不是经过确认的替代值。 在启用更新之前，请分别测试 identified 结果、unknown 结果和错误这三条分支。使用虚构的示例响应，可以在不发送新预测的情况下检查分支条件。目标应用中的更新必须依赖上述检查，并且不得覆盖与之无关的字段或标签。 - [响应字段与未知结果](https://www.genderapi.io/zh/docs/v2/responses) - [准确性与置信度说明](https://www.genderapi.io/zh/accuracy-methodology) - [数据来源与注明日期的数据库概况](https://www.genderapi.io/zh/data-provenance) ## 控制重试和重复计费 Pipedream 的文档说明，根据方案不同，可以从失败的步骤开始自动重试。请检查这些设置以及所选 HTTP 操作的重试行为。对失败的补充数据步骤进行重试可能会产生新的费用。目标系统后续出现的故障应使用已保存的补充数据输出来修正。 每一次新的 GenderAPI 请求都是一次独立的操作。请在发送之前，利用已保存的源 ID 和处理状态，在工作流中对重复的源事件进行去重。源记录 ID 并不是服务器端防止重复的键。 已完成的 unknown 结果是一个完整且计费的结果。如果出现超时或响应不完整，结果和计费情况都可能未知：如果有请求引用，请保存它，并在重新发送请求之前核实计费情况。当请求频率超限的响应带有 Retry-After 响应头时，请遵守该值。 - [积分与计费状态](https://www.genderapi.io/zh/docs/v2/credits-and-usage) ## 决定何时使用 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 | - [AI 选项与昵称解读](https://www.genderapi.io/zh/docs/v2/ai-options) - [积分与用量](https://www.genderapi.io/zh/docs/v2/credits-and-usage) ## 扩大处理量之前先检查工作流 - 通过一次有限的测试，检查实际序列化后的 JSON、解析出的结果路径、API 密钥访问以及计费确认。如果可能，请用示例响应测试 unknown 结果和错误的处理方式。 - 明确工作流中哪些步骤会重复执行，以及会修改哪些客户字段。保存源记录 ID、收到的响应和请求引用，这样目标系统稍后出现故障时就不需要再发送一次请求。 - 先启用一次小规模的受控运行，检查记录和积分后再提高并发。GenderAPI 积分与自动化平台按任务或操作收取的费用是两笔独立的费用。 - 对于批量处理，请使用 POST /api/v2/gender/batch：使用 API 密钥访问时最多 50 个条目，使用 IP 试用时最多 10 个。items 数组可以混合包含姓名、电子邮箱地址和用户名，每个条目都带有明确的选项和唯一的 ID。请逐一检查每个结果：HTTP 200 响应中也可能包含单个条目的错误。原生连接器是否支持批量处理，需要另行核实。 - [批量请求与单个条目的错误](https://www.genderapi.io/zh/docs/v2/batch) - [Python 实施指南](https://www.genderapi.io/zh/integrations/python) - [Node.js 实施指南](https://www.genderapi.io/zh/integrations/javascript) ## 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日进行的审核是对翻译的核对，并不是用账户进行的新测试。在启用生产环境中的更新之前，请用您自己的账户核实所选操作当前的字段、身份验证、请求体、响应和重试行为。 ## 来源与文档 - [Pipedream 上的 GenderAPI.io 应用](https://pipedream.com/apps/genderapi-io) - [Pipedream 公开的 GenderAPI.io 组件](https://github.com/PipedreamHQ/pipedream/blob/master/components/genderapi_io/genderapi_io.app.mjs) - [Pipedream 中的 HTTP 请求操作](https://pipedream.com/docs/workflows/building-workflows/http) - [Pipedream 中的机密环境变量](https://pipedream.com/docs/workflows/environment-variables) - [Pipedream 中的工作流设置与重试](https://pipedream.com/docs/workflows/building-workflows/settings) - [GenderAPI.io V2 请求契约](https://www.genderapi.io/zh/docs/v2/request-parameters) - [GenderAPI.io V2 响应契约](https://www.genderapi.io/zh/docs/v2/responses) - [GenderAPI.io V2 计费与积分](https://www.genderapi.io/zh/docs/v2/credits-and-usage)