从账户面板开始处理文件
GenderAPI 文件工具会读取一个工作表，让您映射一列姓名、电子邮箱地址或用户名，并生成补充数据后的 CSV 导出文件。如果您不需要构建 API 集成，可以用它来进行基于文件的处理。
账户面板中的这一工作流与 REST V2 的批量请求是分开的。文件并不是 V2 的 JSON 请求：V2 的单条目限制和响应路径不适用于这种内置处理。
使用文件选择器支持的格式
当前的文件选择器一次只接受一个文件。对于包含多个工作表的工作簿，请选择正确的工作表并检查载入的值。如果文件是其他格式，请在开始之前将其导出为上面列出的某种格式。
处理过程取决于文件的复杂程度、行数、所选方法、账户积分和服务负载。请用具有代表性的文件进行测试；本指南不承诺固定的最大文件大小或固定的处理时间。
| 格式 | 支持的文件类型 |
|---|---|
| CSV | .csv |
| Excel | .xls, .xlsx |
| Apple Numbers | .numbers |
| OpenDocument | .ods |
| 制表符分隔值 | .tsv |
| 文本 | .txt |
开始处理之前先检查建议
- 制作一份只包含所需数据的副本。把输入放在一个名称清晰的列中，并把可靠的两位字母国家/地区代码（如有）放在单独的列中。
- 登录后打开 Excel/CSV 工具，选择正确的密钥，然后选择文件和工作表。
- 在设置工作表时，工具可能会发送示例单元格，借助 AI 来建议列。继续之前，请您亲自检查输入类型和建议的列。
- 选择对姓名、电子邮箱地址或用户名进行分析，确认源列和可选的国家/地区映射，然后检查工具显示的 AI 和导出选项。
- 开始处理并关注进度。不要仅仅因为处理尚未完成就多次上传同一个文件。
- 导出完成后，下载 CSV 文件，确认各行一一对应，并复核已识别、unknown 和失败的记录。请保留源文件以便比较。
检查文件处理的设置
| 设置 | 类型 | 说明 |
|---|---|---|
| API 密钥 | 账户凭据 | 本次处理使用其余额的账户。 |
| 文件和工作表 | 文件选择 | 一个受支持的文件以及正确的工作表。 |
| 方法 | 选项 | name、email 或 username。请检查自动建议的值。 |
| 源列 | 列映射 | 每一行中需要分析的输入；请检查标题行和示例值。 |
| 国家/地区背景 | 可选的列或选项 | 在相关时使用已知的两位字母国家/地区代码。 |
| AI 和导出选项 | 工具当前的控件 | 处理之前请检查显示的选项；它们不是 V2 的 ai_mode 参数。 |
读取结果列
导出的 CSV 文件会附加内置的结果字段 gender、country、probability 和 found_name。在把文件导入其他系统之前，请确认各行与原始文件一一对应，并检查列标题。即使输入是 Excel 工作簿，结果也会以 CSV 格式提供。
预测是推断出的关联。请把它们与本人自述的性别以及经过核实的国家/地区信息分开保存。
- 在处理整个数据集之前，请先检查一个普通结果、一个含义不明确的输入和一次失败的运行。
- 空单元格、文本 null 和公式错误是不同的值。请有意识地统一 unknown 结果的表示方式，但不要掩盖错误。
- 对于 unknown 或不确定的情况，请使用中性的表述，并把本人提供的信息与预测分开保存。
| 结果 | 类型 | 使用方式 |
|---|---|---|
| Gender | 文本或未解析的值 | 只有在结果成功时才保存 male 或 female。把未解析的值保存为 unknown，并单独检查错误信息。 |
| Probability | 数值（如有） | 一个沿用下来的置信度指标。它并不对应 V2 的 confidence 字段，也不代表在您的数据上实测的准确率。 |
| Country | 文本（如有） | 查询返回的背景信息。请把它与经过核实的客户国家/地区分开保存。 |
| Found / normalized name | 文本（如有） | 处理过程中使用或提取出的名字。当电子邮箱地址或用户名含义不明确时，请检查这一值。 |
规划积分、限制和重新运行
已注册的免费 GenderAPI 账户每天包含 200 个积分。这是账户余额，并不承诺每个工作流都能得到 200 个已识别的结果。开始之前，请检查所选密钥的余额以及该工具当前的处理选项。
插件和文件处理遵循各自的处理流程。V2 REST API 的批量限制、AI 选项和每个请求的计费字段并不会自动适用于这些工具。重新运行或重新计算可能会发送新的请求并消耗积分，因此不要默认它是免费的。
请先从小样本开始，保存已得到的结果，并在重新运行之前复核失败的行。如果您只需要修正一次导出或目标系统中的更新，请复用已有的结果。
了解文件的预先分析与存储
在最终处理开始之前，选择工作表时可能会发送示例单元格，用于借助 AI 映射列。不要以为在您开始处理之前，所有数据都只保留在您的设备上。请删除不需要的列，并在选择包含个人数据的文件之前阅读隐私政策。
导出之后，如果您不再需要工作区中的副本，可以使用提供的删除功能。已发布的政策说明了从活动系统中按计划删除以及在备份中保留的情况；计划中的删除并不能证明所有副本都已被移除。
何时直接使用 V2 API
如果您的应用需要明确的 AI 选项，并需要每个条目的 V2 status、source、confidence_kind 和 usage 信息，请配置单独的 HTTP 集成。请遵循 V2 的请求和响应契约：把 V2 字段名添加到插件自带的公式或现有插件中，并不会改变它们的行为。
常见问题
该工具支持 XLSM 文件吗？
当前的文件选择器显示 CSV、XLS、XLSX、Numbers、ODS、TSV 和 TXT。请把 XLSM 工作簿导出为其中一种格式，并在上传之前检查导出后的值。
列建议总是正确的吗？
不是。请检查输入类型、标题行的处理方式、源列和国家/地区映射。在设置过程中，可能会发送示例数据以获取 AI 辅助的建议。
我会拿回原始的 Excel 工作簿吗？
文档中说明的处理会以 CSV 格式导出结果。在把结果转移到原始工作簿或其他工具之前，请检查导出的列和行的位置。
这相当于一次 V2 批量请求吗？
不是。这是账户面板中的文件处理，有自己的设置和流程。当您在自己的集成中构建 JSON 请求时，请使用 V2 批量请求文档。
来源与文档
本指南最近一次审核于 。请在平台文档中确认安装方式；如需单独构建 V2 集成，请使用下列 API 文档。