接口文档

文识云对外提供 AI 文本检测与 AI 图片检测两类接口，均为异步：提交立即返回 task_id，再用它轮询结果。全部接口共用同一个 API Key 与同一份余额。

最近更新：2026-10-18

概览

所有接口的响应体结构一致：成功时 code 为 "ok"，业务数据放在 data 里；失败时返回对应的 HTTP 状态码，并在 code 与 message 里说明原因，此时没有 data。

接口路径以 /v1 开头。 本站没有匿名可读的对外接口，包括计价规则在内，所有 /v1 接口都需要携带 API Key。

需要机器可读的契约（字段类型、必填项、枚举值）时，直接取 OpenAPI 描述文件：OpenAPI 3.1 格式，可导入 Postman、Apifox、Swagger UI，也可以直接交给 AI 编程助手生成调用代码——比让它从下面的示例里猜字段类型可靠。

快速开始

先在用户中心生成密钥，然后按下面的示例提交并轮询。示例中的域名与密钥都需要替换成你自己的。

# 1. 提交检测任务（提交即扣费，务必携带 Idempotency-Key）
#    幂等键任意 <=64 字符的随机串即可。这里读内核提供的 UUID，不用 uuidgen ——
#    它属于 uuid-runtime 包，最小化安装的 Debian/Ubuntu 上默认没有。
#    is_merge=false 让每个段落独立出置信度（分段检测）；省略或 true 则合并为整体判定
curl -X POST https://your-domain.com/v1/text/classify \
  -H "Authorization: Bearer sk-zq-你的密钥" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \
  -d '{"text":"这是一段待检测的文本","is_merge":false}'

# 2. 用返回的 task_id 轮询结果（pending / running / succeeded / failed）
curl https://your-domain.com/v1/tasks/<task_id> \
  -H "Authorization: Bearer sk-zq-你的密钥"

响应示例

{
  "code": "ok",
  "data": {
    "task_id": "01J8Z9K3M7X2Q4R6T8V0W1Y5BC",
    "provider": "zhuque-text",
    "status": "succeeded",
    "cost": "0.0600",
    "result": {
      "status": "success",
      "softmax_confidence": 0.9987,
      "ratio_confidence": 0.9821,
      "labels_ratio": { "0": 0.35, "1": 0.65 },
      "segment_labels": [
        {
          "text": "前半段人工撰写的内容",
          "label": 0,
          "conf": 0.0121,
          "order": 1,
          "position": [0, 10]
        },
        {
          "text": "后半段由模型生成的续写",
          "label": 1,
          "conf": 0.9976,
          "order": 2,
          "position": [10, 11]
        }
      ]
    },
    "error_code": null,
    "error_msg": null,
    "latency_ms": 1832,
    "created_at": "2026-10-10T15:32:14+08:00",
    "finished_at": "2026-10-10T15:32:16+08:00"
  }
}

segment_labels[].position 是 [start, length]：第二项是段长（按 Unicode 字符计），不是结束下标。

用 Python 的话，也可以直接装官方 SDK（pip install aigc-detect），提交、轮询、幂等重试与错误分类都已封装好，无需手写下面的循环。详见 Python SDK 与各语言示例。

鉴权

每个请求都要带上 Authorization: Bearer sk-zq-…。密钥只在创建时完整显示一次，之后只能看到前缀；泄露后请在用户中心立即删除并重建。

提交类接口还必须带 Idempotency-Key（不超过 64 个字符的随机串）。同一个键重复提交只会执行一次、只扣一次费，因此网络超时后的重试应当复用原键；换了参数就当新请求，要换新键。

接口列表

POST/v1/text/classify

提交文本检测任务，立即返回 task_id（异步，不返回结果）

必须携带 Idempotency-Key，缺失会直接返回 400。

{
  "text": "这是一段待检测的文本",
  "is_merge": false
}

text 必填，上限 20000 个字符（按 Unicode 字符计，不是字节）。超限直接返回 400，不会进入检测流程。
is_merge 控制分段粒度：false 时每个段落独立出置信度，结果在 result.segment_labels；省略或 true 时合并为整体判定，返回体积更小。需要逐段定位 AI 生成片段时用 false，只要整体结论时用 true。
改这个参数等于换了一次提交，重试时应换用新的 Idempotency-Key：幂等是按「账号 + 键」去重的，不校验请求内容，复用旧键会直接返回上一次的任务。

POST/v1/image/classify

提交图片检测任务，立即返回 task_id（异步，不返回结果）

必须携带 Idempotency-Key，缺失会直接返回 400。

{
  "image_url": "https://example.com/a.png"
}

image_url 与 image_base64 二选一：前者是公网可访问的 http/https 地址，后者是图片内容的 Base64 编码。
两个字段都同时接受 camelCase 写法（imageUrl / imageBase64），从上游文档直接迁移过来的代码不必改写字段名。
支持 jpg / png / webp；图片需大于 300×300 像素，单张解码后不超过 10MB，请求体整体不超过 16MB。

GET/v1/tasks/{task_id}

查询任务状态与结果，取结果的唯一方式

status 取值为 pending / running / succeeded / failed；前两者是中间态，需要继续轮询，后两者是终态。
只能查询本账号提交的任务，别人的 task_id 一律 404。
轮询间隔建议不小于 1 秒：查询接口有独立的每秒上限，但密集轮询换不来更快的结果——推理耗时由上游决定。

GET/v1/usage

分页查询本账号的调用记录（与 /v1/tasks/{id} 返回同一形状）

查询参数：limit 默认 20、最大 100；offset 最大 100000。
响应为 { list, total, limit, offset }：list 无记录时是 []，total 用于判断是否还有下一页。
列表项与单条查询的字段完全一致，前端可以复用同一套渲染。

GET/v1/pricing

查询当前生效的计价规则

该接口同样在 /v1 分组内，需要携带 API Key（本站没有匿名可读的对外接口）。
返回的是实时规则：运营在管理后台改价后，这里立即反映，不必等发版。

任务状态与结果字段

status 为 pending 或 running 时任务仍在执行，继续轮询即可；succeeded 与 failed 是终态，出现后不必再查。

成功时 result 里的 softmax_confidence 与 ratio_confidence 是两个口径的整体置信度，labels_ratio 是各标签占比；segment_labels 是逐段结果，仅在 is_merge=false 时有意义。其中 position 是 [起始位置, 段长]，第二项是长度而不是结束下标。

计费与退款

金额制（元），提交时按实际用量扣费，每次调用有最低收费封底。

字符数的计算口径：提交时先剔除首尾空白，再按 Unicode 字符计数（不是 UTF-8 字节）；文本中间的空格、换行与标点全部计入。费用按价格表中的计价单位向上取整，不足一个单位按一个单位计（如每 1000 字计价时，1 字符与 999 字符都按 1000 字计费）。

检测类型	计价单位	单价	最低收费
AI 图片检测	每张	¥0.05	¥0.05
AI 文本检测	每 1000 字	¥0.06	¥0.06

退款只发生在「请求没有被受理」时：参数不合法、触发限流、检测服务不可用，这些情况会自动全额退回。请求已经送达并开始推理之后的失败（超时、上游异常、结果未取回）不退款。是否退款以资金流水里有没有对应的退款记录为准。

错误码

HTTP 层错误。响应体为 { code, message }。

状态码	code	含义
400	`invalid_param`	请求体不是合法 JSON，或参数不合法（如 text 为空、超出长度上限）
400	`missing_idempotency_key`	提交类接口未携带 Idempotency-Key 请求头
401	`invalid_api_key`	API Key 缺失、格式错误、已禁用，或归属账号不存在
402	`insufficient_balance`	余额不足，需要先充值
403	`account_disabled`	归属账号已被停用
403	`provider_disabled`	该检测类型当前未开放
404	`not_found`	任务不存在，或不属于当前账号
413	`payload_too_large`	请求体超过上限（默认 16MB）
429	`rate_limited`	超出每秒请求上限，响应头 Retry-After 给出建议等待秒数
429	`quota_exceeded`	超出每日提交配额（口径是成功扣费的提交次数，不是到达接口的请求数）
500	`internal_error`	服务内部错误，详情见服务端日志
504	`timeout`	处理超时

任务已提交成功、但在后台执行失败时不返回 HTTP 错误码，而是体现在任务的 error_code 字段（HTTP 仍是 200）。只有这一层能确定退款口径，所以只在这里标注：

error_code	含义	退款
`bad_request`	输入未被受理，检查内容后重试	全额退
`rate_limited`	检测服务繁忙，稍后重试	全额退
`service_unavailable`	检测服务暂时不可用	全额退
`service_error`	检测服务异常，请求已送达	不退
`detect_failed`	检测未能完成（结果未取回）	不退
`timeout`	检测超时	不退
`internal_error`	内部错误，可联系客服排查	不退

error_code 会随实现演进，不建议在代码里穷举匹配。除上表之外还可能出现少量内部调度类错误码，它们同属「请求未被受理」，会自动全额退款；认不出的码按 failed 处理、以资金流水为准即可。

用量限制

项目	限制
单次文本长度	20000 字符
单张图片大小	解码后 ≤ 10MB
请求体大小	≤ 16MB
幂等键长度	≤ 64 字符
提交频率	默认 2 次/秒（按账号）
查询频率	默认 10 次/秒（按账号）
每日提交配额	默认 1000 次（按账号，东八区日界）
分页上限	limit ≤ 100，offset ≤ 100000

上表为默认值，部署方可以调整；实际生效的限制以服务端返回的状态码为准。超出提交频率返回 429（响应头 Retry-After 给出建议等待秒数），需要更高配额可以联系我们调整。

返回首页用户中心用户协议隐私政策