AB
AB
AiBoss

All Categories

Tutorials

GPTZero

Tutorials

GPTZero API 快速上手：从获取密钥到解读检测结果

面向开发者的 GPTZero API 入门教程：创建并保存 API 密钥、调用文本检测接口、读懂 predicted_class 与 class_probabilities 等返回字段，并梳理文件检测、AI 模式流式接口、参考文献扫描与用量查询等端点及字符上限、密钥报错等限制。

GPTZero 提供了一套用于判断文本是否由 AI 生成的 API。它适合需要把 AI 内容检测能力嵌入自己产品的开发者，例如作业提交系统、内容审核流程、编辑后台或学术工具。整套接口托管在 https://api.gptzero.me，通过 HTTP 请求调用，用 curl 就能完成第一次检测。如果你更习惯在浏览器里直接试请求，可以先打开本站的 GPTZero 工具页了解入口，再回到本文按步骤接入 API。

本文按「准备 → 调用 → 解读 → 扩展」的顺序展开：先说明账号与密钥的准备，再给出文本检测的完整请求与响应，然后逐个介绍文件检测、AI 模式流式接口、参考文献扫描和用量查询等端点，最后列出素材中明确写出的限制与常见坑。

准备工作

账号与 API 密钥

调用 GPTZero API 需要一个 GPTZero 账号。登录后进入应用中的 API 页面创建密钥。密钥只在创建时完整展示，拿到后应立即保存到安全位置。

推荐把密钥放进环境变量，而不是写死在代码或脚本里：

export GPTZERO_API_KEY="your-api-key"

密钥等同于账号的调用凭证，任何拿到它的人都能以你的账号发起请求、消耗你的额度。不要把密钥提交到代码仓库，也不要在客户端代码里硬编码。

调用环境

素材中的示例命令在 Bash 或 Zsh 下运行，需要本机装有 curl。请求体使用 JSON，因此还需要在请求头里声明 Content-Type: application/json。

认证方式与报错含义

所有端点都通过请求头 x-api-key 传递密钥。认证失败时返回的状态码有明确区分：

  • 401：密钥缺失或已过期。
  • 403：密钥无法识别。

排查问题时先看状态码，能快速区分「没带密钥 / 密钥过期」和「密钥本身不对」两类情况。

验证密钥是否可用

在正式写业务代码之前，可以先查询当前计费周期的用量，确认密钥有效：

curl https://api.gptzero.me/v3/usage-stats \
  -H "x-api-key: $GPTZERO_API_KEY"

这个请求同时也能让你看到当前套餐和已用、剩余的额度，便于后续估算调用量。

操作步骤

第一步：准备请求体

文本检测接口是 POST /v2/predict/text，请求体里只有一个必填字段 document，值为待检测的文本字符串。文本可以包含换行，接口会按段落和句子拆分后分别给出结果。

素材给出的示例是一段混合文本：前半部分是关于气候变化的 AI 生成内容，后半部分是一段关于苏格兰山地植物的人类写作。用这种混合样本可以同时观察接口对 mixed 类的判定。

第二步：发送检测请求

下面这条命令把 JSON 直接通过标准输入传给 curl。注意 << 'JSON' 中的引号不能省：它让 shell 不做变量替换和转义处理，样本里的撇号等字符才能原样保留。

curl https://api.gptzero.me/v2/predict/text \
  -H "x-api-key: $GPTZERO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- << 'JSON'
{
  "document": "Climate change refers to the long-term shift in global weather patterns caused by human activity, particularly the emission of greenhouse gases into the atmosphere. The most significant greenhouse gas is carbon dioxide, which is primarily produced by burning fossil fuels such as coal, oil, and gas. The consequences of climate change are already visible in the form of rising temperatures, melting glaciers and ice caps, and more frequent extreme weather events such as hurricanes, droughts, and floods. These changes have significant impacts on ecosystems, biodiversity, and human health, including increased risk of respiratory diseases, food and water shortages, and the spread of infectious diseases. To address climate change, it is essential to reduce greenhouse gas emissions through a range of measures, including increased use of renewable energy sources, greater energy efficiency, and improved transportation systems. \nClimate change has likely led to the decline of some of Scotland's mountain plants, according to new research. Scientists said many of the species relied on snow cover remaining high on hills until late spring and even summer to ensure a moist environment. They also said plants that thrived on lower ground in warmer conditions were spreading to mountain habitats. Species found to be in decline include snow pearlwort, alpine lady-fern and alpine speedwell. The research by the Botanical Society of Britain and Ireland (BSBI) has taken 20 years to complete and has been published in the new Plant Atlas. Data used to produce the report included more than three million plant records of 2,555 species collected by hundreds of botanists across Scotland."
}
JSON

如果不想用标准输入，也可以把 JSON 存成文件，再用 --data-binary @payload.json 指定文件路径，效果相同。

第三步：读取响应

响应中的 documents 数组对应你提交的文本，每个元素包含该文档的检测结论。素材记录的混合文本示例响应如下（省略了句子级明细等字段）：

{
  "documents": [
    {
      "predicted_class": "mixed",
      "class_probabilities": {
        "human": 0,
        "ai": 0.000051549673295649754,
        "mixed": 0.9999484503267044
      },
      "confidence_category": "high",
      "result_message": "Our detector is highly confident that the text may include parts written by AI."
    }
  ],
  "version": "2025-11-28-base"
}

建议优先关注以下四个字段：

  • predicted_class：检测器认为最可能的类别，取值为 human、ai 或 mixed。
  • class_probabilities：三个类别各自的概率，取值范围 0 到 1，三者之和为 1。
  • confidence_category：检测器对 predicted_class 这一结论的置信程度。
  • result_message：一句可以直接展示给终端用户的说明文字。

顶层的 version 字段标明本次检测使用的模型版本。检测器会持续更新，因此同样的文本在不同时间调用，分数和模型版本都可能不同。做回归测试或结果对比时，应把 version 一并记录下来。

一个完整示例

下面把前面的步骤串成一个可以直接执行的脚本，从设置密钥到打印关键字段：

#!/usr/bin/env bash
set -euo pipefail

export GPTZERO_API_KEY="your-api-key"

# 1. 验证密钥并查看用量
curl -s https://api.gptzero.me/v3/usage-stats \
  -H "x-api-key: $GPTZERO_API_KEY"

# 2. 提交一段文本做检测
curl -s https://api.gptzero.me/v2/predict/text \
  -H "x-api-key: $GPTZERO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- << 'JSON'
{
  "document": "Climate change refers to the long-term shift in global weather patterns caused by human activity. The most significant greenhouse gas is carbon dioxide, which is primarily produced by burning fossil fuels. To address climate change, it is essential to reduce greenhouse gas emissions through a range of measures."
}
JSON

执行后你会得到一份 JSON。业务代码里通常只需要取 documents[0].predicted_class 做分支判断，把 documents[0].result_message 展示给用户，并把 version 写入日志。如果 predicted_class 为 mixed，说明文本中可能同时存在人工撰写与 AI 生成的部分，此时应结合段落级、句子级明细进一步定位。

其他端点

文件检测

POST /v2/predict/files 用于上传文件并检测其中的 AI 内容，每个文件返回一条结果。单次请求最多上传 250 个文件，每个文件最大 50 MB。从文件中提取出的文本会被截断到套餐的字符上限，API 套餐下为 150,000 字符。

AI 模式流式接口

POST /v3/ai/patterns/stream 用于找出文档中的 AI 写作模式（例如「三段式」排比结构），并用通俗语言解释每一处匹配。结果以 Server-Sent Events 形式流式返回，每个事件是一行 data: <json>，其中 JSON 对应一个句子及其命中的模式。没有命中任何模式的句子会被跳过，连接关闭即表示流结束。

使用这个接口时有几个细节需要注意：

  • 服务端每 30 秒发送一条 :keepalive 注释，标准 SSE 客户端会自动忽略它。
  • 流开始之后如果处理失败，HTTP 状态码已经是 200，错误会以最后一条 data: {"error": "Error in streaming AI patterns"} 事件的形式到达。因此必须逐个事件检查是否存在 error 字段，不能只看状态码。
  • AI Patterns 默认不开启，你的 API 密钥需要被加入允许名单后才能调用。

参考文献扫描

参考文献扫描用于检查文档中的引用与论断：找出引用、核实每条引用是否存在，并返回匹配到的来源。它有两个端点：

  • POST /v2/bibliography-scan/text：扫描单个文档的文本。超过套餐字符上限会返回 400，API 套餐下上限为 150,000 字符。
  • POST /v2/bibliography-scan/files：对每个上传文件执行扫描，每个文件返回一条结果。

用量与模型版本

GET /v3/usage-stats 返回当前计费周期内已用字数、剩余字数以及套餐信息。GET /v2/model-versions/ai-scan 返回可以作为 modelVersion 传入的模型版本列表。

需要注意，模型版本列表可能包含尚未正式发布的版本。哪些版本被批准使用、每个版本改进了什么，应以发布说明为准，不要直接把列表里的第一个版本当作可用版本。

注意事项

  • 字符上限：文本检测与参考文献扫描（文本）在文本超过套餐字符上限时返回 400。API 套餐下上限为 150,000 字符。文件检测不会报错，而是把提取出的文本截断到该上限，因此长文件的结果只覆盖前面部分。
  • 文件数量与大小：单次文件检测请求最多 250 个文件，每个文件最大 50 MB。
  • 语言处理：文本检测会自动识别语言，非英文文本使用多语言模型扫描。
  • 结果会变化：检测器持续更新，相同文本的分数与模型版本可能不同，不要把某次分数当作固定基准。
  • 流式接口的错误处理：AI Patterns 流开始后出错仍返回 200，必须检查每个事件里的 error 字段。
  • 功能开通：AI Patterns 不是默认开启的功能，密钥需要被加入允许名单。
  • 密钥安全：密钥泄露等同于账号被他人使用，务必通过环境变量或密钥管理服务注入。
  • 套餐与配额：字符上限、可用功能与用量额度随套餐变化，具体数值与价格请以官网当前信息为准。

把以上端点按需组合，就可以搭建一条从文本或文件输入、到检测结论、再到引用核验的完整处理链路。建议先在测试环境用短文本跑通认证与响应解析，再接入批量文件与流式场景。

Back