提交接口

完整的「上传 → 查重 → 下载报告」流程。所有接口均需 Authorization: Bearer <api_key>。

1. 上传文档

POST /app/api/uploads
Content-Type: multipart/form-data

字段：

字段	类型	必须	说明
file	File	✓	PDF / DOCX / TXT，≤ 50 MB

响应：

{
  "upload": {
    "id": "upl_xxxxxxxx",
    "filename": "paper.pdf",
    "content_type": "application/pdf",
    "size_bytes": 214528,
    "word_count": 2847,
    "created_at": "2026-04-18T12:34:56Z"
  }
}

2. 创建提交

POST /app/api/submissions
Content-Type: application/json

Body：

{
  "upload_id": "upl_xxxxxxxx",
  "reports": ["similarity", "ai"],
  "metadata": {
    "paper_title": "Research Paper"
  }
}

字段说明：

字段	类型	说明
upload_id	string	上一步拿到的 upload id
reports	string[]	`similarity` / `ai` 任选一个或两个
metadata	object	可选；客户侧自定义字段，会回写到报告响应

响应（成功）：

{
  "submission": {
    "id": "sub_xxxxxxxx",
    "status": "queued",
    "credits_reserved": 2,
    "created_at": "2026-04-18T12:34:59Z"
  }
}

错误码：

状态	错误码	说明
402	insufficient_credits	余额不足
400	invalid_input	参数校验失败
404	upload_not_found	upload_id 不存在或不属于当前用户
409	upload_already_used	同一 upload 已被创建过提交

3. 查询状态

GET /app/api/submissions/:id

响应 status 取值：

queued — 排队中
running — 正在获取报告
completed — 完成
failed — 失败（failure_code 解释原因，平台侧失败自动返还积分）

完成响应会包含每份报告的分数：

{
  "submission": {
    "id": "sub_xxxxxxxx",
    "status": "completed",
    "credits_reserved": 2,
    "credits_consumed": 2,
    "reports": {
      "similarity": { "score": 18, "overall_color": "blue" },
      "ai": { "probability": 6, "overall_color": "low" }
    },
    "completed_at": "2026-04-18T12:37:04Z"
  }
}

4. 下载报告

GET /app/api/submissions/:id/report?type=similarity
GET /app/api/submissions/:id/report?type=ai

返回 application/pdf。若要获取结构化 JSON，追加 ?format=json：

{
  "report": {
    "type": "similarity",
    "score": 18,
    "submitted_text_word_count": 2847,
    "source_matches": [ /* ... */ ]
  }
}

5. 列表

GET /app/api/submissions?limit=50

按时间倒序返回当前 principal 下的提交记录。Guest（未注册）只能看到当前 session 下的提交；登录后继承 guest 记录。

实时事件（SSE）

查看任务每一步的状态变化：

curl -N https://turnitin.example.com/v1/jobs/<jobId>/events \
  -H "Authorization: Bearer sk_live_xxxxx"

事件类型：lifecycle.queued、lifecycle.leased、workflow.login、workflow.submit、workflow.poll_similarity、workflow.poll_ai、lifecycle.completed、lifecycle.failed。