快速开始

本指南面向已在控制台创建 Managed API Key 的开发者。Key 必须属于一个启用中的客户账户；浏览器 Cookie 接口在 /app/api/* 下，不能拿 Bearer Key 调用。

1. 创建 API Key

登录控制台后进入 API Keys 页，点击「创建新 Key」。系统只会显示一次明文 Key，请立即保存到密码管理器。

export TURNITIN_API_KEY="ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. 上传文档

curl -X POST https://turnitinai.vip/v1/uploads \
  -H "Authorization: Bearer $TURNITIN_API_KEY" \
  -F "file=@./paper.pdf"

响应中的 upload_id 是后续提交唯一接受的上传引用：

{
  "upload_id": "upl_xxxxxxxx",
  "filename": "paper.pdf",
  "size": 214528,
  "word_count": 2847,
  "mime_type": "application/pdf",
  "status": "pending"
}

不要把兼容响应字段 file_key 当作提交参数。

3. 获取冻结报价

报价冻结本次上传、报告组合和额度成本。保存返回的 quote_id：

curl -X POST https://turnitinai.vip/v1/submissions/quote \
  -H "Authorization: Bearer $TURNITIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_xxxxxxxx",
    "report_types": ["similarity", "ai"]
  }'

{
  "quote": {
    "upload_id": "upl_xxxxxxxx",
    "report_types": ["similarity", "ai"],
    "upload_word_count": 2847,
    "credits_cost": 2,
    "quote_id": "qte_xxxxxxxx",
    "provider_plan_id": "pln_xxxxxxxx",
    "estimated_provider_cost_usd": null,
    "estimated_provider_cost_cny": null
  }
}

4. 幂等创建提交

curl -X POST https://turnitinai.vip/v1/submissions \
  -H "Authorization: Bearer $TURNITIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submission-20260804-0001" \
  -d '{
    "upload_id": "upl_xxxxxxxx",
    "report_types": ["similarity", "ai"],
    "quote_id": "qte_xxxxxxxx"
  }'

Idempotency-Key 是必填项。网络重试必须复用完全相同的 Key 和请求体；复用 Key 但改变上传、报告组合或报价会返回冲突，而不是第二次上游提交。

{
  "submission": {
    "id": "sub_xxxxxxxx",
    "status": "queued",
    "report_types": ["similarity", "ai"],
    "credits_cost": 2,
    "credits_refunded": 0,
    "report_exists": { "similarity": false, "ai": false }
  },
  "links": {
    "submission_url": "/v1/submissions/sub_xxxxxxxx",
    "events_url": "/v1/submissions/sub_xxxxxxxx/events",
    "job_url": null
  }
}

5. 等待报告

轮询 submission：

curl https://turnitinai.vip/v1/submissions/sub_xxxxxxxx \
  -H "Authorization: Bearer $TURNITIN_API_KEY"

或订阅 SSE：

curl -N https://turnitinai.vip/v1/submissions/sub_xxxxxxxx/events \
  -H "Authorization: Bearer $TURNITIN_API_KEY"

流中有 submission_status 和 job_event 两类事件。submission_status 提供状态和可选 failure_code；job_event 包含原始事件名、occurred_at 和事件数据。SSE 用于进度提示，重连后请再次读取 submission，把其状态和 report_exists 当作恢复后的权威事实。

平台侧终态失败（例如 turnitin_blocked、login_failed）会按原额度分配自动退款；不要仅根据 SSE 的中间事件改变本地账务。

6. 读取报告元数据和文件

/report 返回 JSON 元数据和可选结构化内容：

curl "https://turnitinai.vip/v1/submissions/sub_xxxxxxxx/report?type=similarity" \
  -H "Authorization: Bearer $TURNITIN_API_KEY"

/report/file 返回报告文件字节。请按 Content-Type 和 Content-Disposition 处理响应，不要把 JSON 接口当作下载接口：

curl "https://turnitinai.vip/v1/submissions/sub_xxxxxxxx/report/file?type=similarity" \
  -H "Authorization: Bearer $TURNITIN_API_KEY" \
  -o similarity.pdf

将 type 改为 ai 可读取 AI 报告。报告尚未可用时接口返回 report_not_ready。

常见问题

报告一直 queued：读取 submission 的 status 和 failure_code；不要改用旧 /v1/jobs 创建入口。
401 Unauthorized：Authorization header 格式应为 Bearer <key>，注意没有多余空格。
402 insufficient_credits：额度不足。当前在线收款保持关闭，请使用已获得的额度或兑换码。