xiaoxia-saas/docs/API-REFERENCE-v0.1.88.md

小虾 SaaS API 参考文档

版本: v0.1.88
更新日期: 2026-06-29
基础 URL: /api/v1

---

目录

1. 认证 (Auth)
2. 项目 (Project)
3. 任务中心 (TaskCenter)
4. 素材诊断 (AssetDiagnosis)
5. 素材库 (AssetLibrary)
6. 素材 (Asset)
7. 导入任务 (IngestJob)
8. 分类任务 (ClassificationJob)
9. 上传 (Upload)
10. 分片上传 (ChunkedUpload)
11. 生成任务 (Generation)
12. 生成视频 (GeneratedVideo)
13. 标题库 (TitleLibrary)
14. 配音库 (VoiceLibrary)
15. 查重 (Duplication)
16. 订阅 (Subscription)

---

通用说明

认证方式

除特别说明外，所有 API 端点均需要认证。认证通过以下方式：

请求头:

Authorization: Bearer <access_token>

获取 access_token 请参见 登录接口。

错误响应格式

{
  "detail": "错误描述信息"
}

HTTP 状态码

状态码	说明
200	请求成功
201	资源创建成功
204	请求成功（无返回内容）
400	请求参数错误
401	未认证或 token 无效
403	无权限访问
404	资源不存在
409	资源冲突
413	文件过大
415	不支持的文件类型
422	请求格式正确但无法处理
429	配额超限
500	服务器内部错误
503	服务暂不可用

---

1. 认证 (Auth)

基础路径: /api/v1/auth

POST /register

用户注册。

认证: 否

请求 Body:

{
  "email": "user@example.com",
  "password": "your_password",
  "username": "username",
  "display_name": "显示名称"
}

字段	类型	必填	说明
email	string	是	邮箱地址
password	string	是	密码（建议至少 8 位）
username	string	是	用户名（唯一）
display_name	string	否	显示名称，默认同 username

响应 201 Created:

{
  "user_id": "用户ID",
  "email": "user@example.com",
  "username": "username",
  "display_name": "显示名称",
  "message": "注册成功！"
}

---

POST /login

用户登录。

认证: 否

请求 Body:

{
  "email": "user@example.com",
  "password": "your_password"
}

响应 200 OK:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user_id": "用户ID",
  "email": "user@example.com",
  "username": "username",
  "display_name": "显示名称",
  "expires_in": 3600
}

---

POST /refresh

刷新访问令牌。

认证: 否

请求 Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

响应 200 OK: 同登录响应

---

GET /verify-email

验证邮箱（通过链接点击）。

认证: 否

查询参数:

参数	类型	必填	说明
token	string	是	邮箱验证 token

响应 200 OK:

{
  "message": "邮箱验证成功"
}

---

POST /verify-email

验证邮箱（通过 API）。

认证: 否

请求 Body:

{
  "token": "邮箱验证 token"
}

响应 200 OK:

{
  "message": "邮箱验证成功"
}

---

POST /password/forgot

请求密码重置。

认证: 否

请求 Body:

{
  "email": "user@example.com"
}

响应 202 Accepted:

{
  "message": "如果账户存在，密码重置邮件已发送"
}

---

POST /password/reset

重置密码。

认证: 否

请求 Body:

{
  "token": "密码重置 token",
  "new_password": "new_password123"
}

响应 200 OK:

{
  "message": "密码重置成功"
}

---

GET /me

获取当前登录用户信息。

认证: 是

响应 200 OK:

{
  "user_id": "用户ID",
  "email": "user@example.com",
  "username": "username",
  "display_name": "显示名称",
  "email_verified": true
}

---

2. 项目 (Project)

基础路径: /api/v1/projects

GET /

获取用户的所有项目列表。

认证: 是

响应 200 OK:

{
  "items": [
    {
      "id": "项目ID",
      "owner_user_id": "拥有者ID",
      "name": "项目名称",
      "description": "项目描述",
      "shared_users": []
    }
  ]
}

---

POST /

创建新项目。

认证: 是

请求 Body:

{
  "name": "项目名称",
  "description": "项目描述（可选）"
}

字段	类型	必填	说明
name	string	是	项目名称（1-100字符）
description	string	否	项目描述（最多500字符）

响应 200 OK:

{
  "id": "项目ID",
  "owner_user_id": "拥有者ID",
  "name": "项目名称",
  "description": "项目描述",
  "shared_users": []
}

---

GET /{project_id}

获取指定项目详情。

认证: 是

路径参数:

参数	类型	说明
project_id	string	项目 ID

响应 200 OK:

{
  "id": "项目ID",
  "owner_user_id": "拥有者ID",
  "name": "项目名称",
  "description": "项目描述",
  "shared_users": []
}

---

3. 任务中心 (TaskCenter)

基础路径: /api/v1

GET /projects/{project_id}/tasks

获取项目的所有任务（导入任务 + 生成任务）。

认证: 是

路径参数:

参数	类型	说明
project_id	string	项目 ID

响应 200 OK:

{
  "items": [
    {
      "id": "task:任务ID",
      "task_type": "ingest 或 generation",
      "project_id": "项目ID",
      "status": "pending | processing | completed | failed",
      "progress": 0.0,
      "current_step": "当前步骤描述",
      "error_message": "",
      "user_message": "",
      "retryable": false,
      "source_id": "原始任务ID",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

---

POST /tasks/{task_type}/{source_id}/retry

重试失败的任务。

认证: 是

路径参数:

参数	类型	说明
task_type	string	任务类型：ingest 或 generation
source_id	string	原始任务 ID

响应 200 OK: 返回重试后的任务信息（同上）

---

4. 素材诊断 (AssetDiagnosis)

基础路径: /api/v1

GET /projects/{project_id}/asset-diagnosis

获取项目的素材健康度诊断。

认证: 是

路径参数:

参数	类型	说明
project_id	string	项目 ID

响应 200 OK:

{
  "project_id": "项目ID",
  "readiness_score": 75,
  "readiness_label": "素材充足",
  "total_assets": 10,
  "ready_assets": 8,
  "video_assets": 5,
  "image_assets": 2,
  "voice_assets": 1,
  "total_duration_seconds": 120.5,
  "estimated_video_count": 3,
  "used_assets": 2,
  "unused_assets": 6,
  "pending_review_assets": 0,
  "smart_views": [
    {
      "key": "recommended",
      "label": "推荐素材",
      "count": 5,
      "description": "已导入完成、可参与生成的视频素材"
    }
  ],
  "gaps": [
    {
      "key": "missing_voice",
      "severity": "info",
      "message": "暂未配置配音素材",
      "recommendation": "如果本项目需要口播/旁白，请上传配音素材"
    }
  ]
}

---

5. 素材库 (AssetLibrary)

基础路径: /api/v1/asset-libraries

GET /

获取素材库列表。

认证: 是

查询参数:

参数	类型	必填	说明
project_id	string	否	按项目 ID 筛选

响应 200 OK:

{
  "items": [
    {
      "id": "素材库ID",
      "project_id": "项目ID",
      "name": "素材库名称",
      "kind": "video | voice | image",
      "asset_count": 10,
      "total_size": 104857600
    }
  ]
}

---

POST /

创建素材库。

认证: 是

请求 Body:

{
  "project_id": "项目ID",
  "name": "素材库名称",
  "kind": "video"
}

字段	类型	必填	说明
project_id	string	是	所属项目 ID
name	string	是	素材库名称（1-100字符）
kind	string	是	类型：video、voice 或 image

响应 200 OK:

{
  "id": "素材库ID",
  "project_id": "项目ID",
  "name": "素材库名称",
  "kind": "video",
  "asset_count": 0,
  "total_size": 0
}

---

6. 素材 (Asset)

基础路径: /api/v1/assets

GET /

获取素材列表。

认证: 是

查询参数:

参数	类型	必填	说明
library_id	string	是	素材库 ID

响应 200 OK:

{
  "items": [
    {
      "id": "素材ID",
      "project_id": "项目ID",
      "library_id": "素材库ID",
      "name": "素材名称.mp4",
      "storage_key": "uploads/xxx/素材名称.mp4",
      "mime_type": "video/mp4",
      "metadata": {},
      "file_size": 10485760,
      "thumbnail_url": "https://...",
      "duration": 120.5,
      "width": 1920,
      "height": 1080,
      "fps": 30.0,
      "codec": "h264",
      "status": "ready",
      "classification_status": "completed",
      "quality_score": 85.0,
      "uploaded_by_user_id": "用户ID"
    }
  ]
}

---

POST /

创建素材记录（通常由上传流程自动调用）。

认证: 是

请求 Body:

{
  "project_id": "项目ID",
  "library_id": "素材库ID",
  "name": "素材名称.mp4",
  "storage_key": "uploads/xxx/素材名称.mp4",
  "mime_type": "video/mp4",
  "metadata": {},
  "file_size": 10485760,
  "thumbnail_url": "https://...",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30.0,
  "codec": "h264",
  "status": "uploading",
  "classification_status": "pending",
  "quality_score": 85.0
}

字段	类型	必填	说明
project_id	string	是	项目 ID
library_id	string	是	素材库 ID
name	string	是	素材名称（1-100字符）
storage_key	string	是	存储路径
mime_type	string	是	MIME 类型
metadata	object	否	元数据
file_size	integer	否	文件大小（字节）
thumbnail_url	string	否	缩略图 URL
duration	float	否	时长（秒）
width	integer	否	宽度
height	integer	否	高度
fps	float	否	帧率
codec	string	否	编码格式
status	string	否	状态（默认 uploading）
classification_status	string	否	分类状态（默认 pending）
quality_score	float	否	质量分数（0-100）

响应 200 OK: 返回创建的素材对象

---

PATCH /{asset_id}/review

更新素材审核状态。

认证: 是

路径参数:

参数	类型	说明
asset_id	string	素材 ID

请求 Body:

{
  "review_status": "pending_review | approved | rejected"
}

响应 200 OK: 返回更新的素材对象

---

7. 导入任务 (IngestJob)

基础路径: /api/v1/ingest-jobs

GET /{job_id}

获取导入任务详情。

认证: 否（内部 API）

路径参数:

参数	类型	说明
job_id	string	任务 ID

响应 200 OK:

{
  "id": "任务ID",
  "project_id": "项目ID",
  "library_id": "素材库ID",
  "storage_key": "uploads/xxx/file.mp4",
  "status": "completed",
  "error_message": "",
  "result_asset_id": "素材ID"
}

---

POST /

提交新的导入任务。

认证: 否（内部 API）

请求 Body:

{
  "project_id": "项目ID",
  "library_id": "素材库ID",
  "storage_key": "uploads/xxx/file.mp4"
}

响应 200 OK: 返回创建的任务对象

---

8. 分类任务 (ClassificationJob)

基础路径: /api/v1/classification-jobs

GET /{job_id}

获取分类任务详情。

认证: 否（内部 API）

路径参数:

参数	类型	说明
job_id	string	任务 ID

响应 200 OK:

{
  "id": "任务ID",
  "project_id": "项目ID",
  "asset_id": "素材ID",
  "status": "completed",
  "classification": "video",
  "confidence": 0.95,
  "error_message": ""
}

---

POST /

提交新的分类任务。

认证: 否（内部 API）

请求 Body:

{
  "project_id": "项目ID",
  "asset_id": "素材ID"
}

响应 200 OK: 返回创建的任务对象

---

9. 上传 (Upload)

基础路径: /api/v1/upload

POST /direct/prepare

准备直传 OSS（获取表单签名）。

认证: 是

请求 Body:

{
  "project_id": "项目ID",
  "library_id": "素材库ID",
  "filename": "video.mp4",
  "content_type": "video/mp4",
  "file_size": 104857600
}

响应 200 OK:

{
  "upload_url": "https://oss.example.com/...",
  "method": "POST",
  "storage_key": "uploads/xxx/video.mp4",
  "expires_at": "2024-01-01T12:00:00Z",
  "fields": {
    "OSSAccessKeyId": "...",
    "policy": "...",
    "signature": "...",
    "key": "uploads/xxx/video.mp4"
  },
  "max_size_bytes": 104857600
}

---

POST /direct/complete

确认直传完成并创建导入任务。

认证: 是

请求 Body:

{
  "project_id": "项目ID",
  "library_id": "素材库ID",
  "storage_key": "uploads/xxx/video.mp4"
}

响应 200 OK:

{
  "storage_key": "uploads/xxx/video.mp4",
  "ingest_job_id": "导入任务ID"
}

---

POST /

上传素材文件（multipart/form-data）。

认证: 是

表单字段:

字段	类型	必填	说明
project_id	string	是	项目 ID
library_id	string	是	素材库 ID
file	file	是	上传的文件

响应 200 OK:

{
  "storage_key": "uploads/xxx/video.mp4",
  "ingest_job_id": "导入任务ID",
  "url": "https://oss.example.com/uploads/xxx/video.mp4"
}

支持的文件类型:

• 视频: video/mp4, video/mpeg, video/quicktime, video/x-msvideo, video/webm, video/x-matroska, video/3gpp
• 音频: audio/mpeg, audio/wav, audio/ogg, audio/flac, audio/aac, audio/mp3, audio/x-m4a
• 图片: image/jpeg, image/png, image/gif, image/webp, image/bmp, image/svg+xml, image/tiff

---

10. 分片上传 (ChunkedUpload)

基础路径: /api/v1/upload/chunk

适用于大文件上传（最大 2GB）。

POST /init

初始化分片上传。

认证: 是

请求 Body:

{
  "filename": "large_video.mp4",
  "file_size": 1073741824,
  "total_chunks": 200,
  "content_type": "video/mp4",
  "project_id": "项目ID",
  "library_id": "素材库ID"
}

字段	类型	必填	说明
filename	string	是	文件名（1-255字符）
file_size	integer	是	文件大小（最大 2GB）
total_chunks	integer	是	分片总数
content_type	string	否	文件 MIME 类型
project_id	string	是	项目 ID
library_id	string	是	素材库 ID

响应 200 OK:

{
  "upload_id": "上传ID",
  "chunk_size": 5242880,
  "total_chunks": 200,
  "filename": "large_video.mp4",
  "expires_at": "2024-01-02T00:00:00Z"
}

---

POST /{upload_id}/{chunk_index}

上传单个分片。

认证: 是

路径参数:

参数	类型	说明
upload_id	string	上传 ID
chunk_index	integer	分片索引（从 0 开始）

请求体: 二进制文件数据

响应 200 OK:

{
  "message": "Chunk uploaded successfully",
  "chunk_index": 0,
  "uploaded_chunks": 1,
  "total_chunks": 200
}

---

GET /{upload_id}/status

获取上传状态（支持断点续传）。

认证: 是

路径参数:

参数	类型	说明
upload_id	string	上传 ID

响应 200 OK:

{
  "upload_id": "上传ID",
  "filename": "large_video.mp4",
  "file_size": 1073741824,
  "total_chunks": 200,
  "uploaded_chunks": [0, 1, 2, 3],
  "status": "uploading",
  "created_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-02T00:00:00Z"
}

---

POST /{upload_id}/complete

完成分片上传，合并文件并创建导入任务。

认证: 是

路径参数:

参数	类型	说明
upload_id	string	上传 ID

请求 Body:

{
  "project_id": "项目ID",
  "library_id": "素材库ID"
}

响应 200 OK:

{
  "storage_key": "uploads/xxx/large_video.mp4",
  "ingest_job_id": "导入任务ID",
  "url": "https://oss.example.com/uploads/xxx/large_video.mp4"
}

---

11. 生成任务 (Generation)

基础路径: /api/v1/generation

POST /tasks

创建视频生成任务。

认证: 是

请求 Body:

{
  "project_id": "项目ID",
  "asset_library_id": "素材库ID",
  "strategy_id": "",
  "voice_library_id": ""
}

字段	类型	必填	说明
project_id	string	是	项目 ID
asset_library_id	string	是	素材库 ID
strategy_id	string	否	生成策略 ID
voice_library_id	string	否	配音库 ID

响应 200 OK:

{
  "id": "任务ID",
  "project_id": "项目ID",
  "asset_library_id": "素材库ID",
  "strategy_id": "",
  "voice_library_id": "",
  "status": "pending",
  "progress": 0.0,
  "result_count": 0,
  "error_message": ""
}

---

GET /tasks/{task_id}

获取生成任务详情。

认证: 是

路径参数:

参数	类型	说明
task_id	string	任务 ID

响应 200 OK: 返回任务详情（同上）

---

GET /tasks/{task_id}/results

获取生成任务的成片列表。

认证: 是

路径参数:

参数	类型	说明
task_id	string	任务 ID

响应 200 OK:

{
  "items": [
    {
      "id": "成片ID",
      "project_id": "项目ID",
      "generation_task_id": "任务ID",
      "name": "成片名称.mp4",
      "file_url": "uploads/xxx/output.mp4",
      "file_size": 5242880,
      "duration": 30.0,
      "thumbnail_url": "https://...",
      "width": 1920,
      "height": 1080,
      "fps": 30.0,
      "status": "completed",
      "review_status": "pending_review",
      "generation_params": {},
      "download_url": "https://..."
    }
  ]
}

---

12. 生成视频 (GeneratedVideo)

基础路径: /api/v1/generated-videos

GET /

获取成片列表。

认证: 是

查询参数:

参数	类型	必填	说明
project_id	string	否	按项目 ID 筛选

响应 200 OK:

{
  "items": [
    {
      "id": "成片ID",
      "project_id": "项目ID",
      "generation_task_id": "任务ID",
      "name": "成片名称.mp4",
      "file_url": "uploads/xxx/output.mp4",
      "file_size": 5242880,
      "duration": 30.0,
      "thumbnail_url": "https://...",
      "width": 1920,
      "height": 1080,
      "fps": 30.0,
      "status": "completed",
      "review_status": "pending_review",
      "generation_params": {},
      "download_url": "https://..."
    }
  ]
}

---

GET /{video_id}

获取成片详情。

认证: 是

路径参数:

参数	类型	说明
video_id	string	成片 ID

响应 200 OK: 返回成片详情

---

PATCH /{video_id}/review

更新成片审核状态。

认证: 是

路径参数:

参数	类型	说明
video_id	string	成片 ID

请求 Body:

{
  "review_status": "pending_review | approved | rejected"
}

响应 200 OK: 返回更新后的成片对象

---

GET /{video_id}/download-url

获取成片下载链接。

认证: 是

路径参数:

参数	类型	说明
video_id	string	成片 ID

响应 200 OK:

{
  "video_id": "成片ID",
  "download_url": "https://oss.example.com/..."
}

---

13. 标题库 (TitleLibrary)

基础路径: /api/v1/titles

GET /

获取标题列表。

认证: 是

查询参数:

参数	类型	必填	说明
category	string	否	按分类筛选
skip	integer	否	跳过数量（默认 0）
limit	integer	否	返回数量（默认 50，最大 200）

响应 200 OK:

{
  "items": [
    {
      "id": "标题ID",
      "user_id": "用户ID",
      "name": "标题名称",
      "text": "标题文本内容",
      "category": "default",
      "description": "描述",
      "tags": ["标签1", "标签2"],
      "usage_count": 5,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 100
}

---

GET /{title_id}

获取标题详情。

认证: 是

路径参数:

参数	类型	说明
title_id	string	标题 ID

响应 200 OK: 返回标题详情

---

POST /

创建标题。

认证: 是

请求 Body:

{
  "name": "标题名称",
  "text": "标题文本内容",
  "category": "default",
  "description": "描述",
  "tags": ["标签1", "标签2"]
}

字段	类型	必填	说明
name	string	是	标题名称（1-255字符）
text	string	是	标题文本（1-500字符）
category	string	否	分类（默认 default）
description	string	否	描述
tags	array	否	标签列表

响应 201 Created: 返回创建的标题对象

配额限制:

• free: 10 条
• standard: 50 条
• pro: 200 条
• enterprise: 无限制

---

PUT /{title_id}

更新标题。

认证: 是

路径参数:

参数	类型	说明
title_id	string	标题 ID

请求 Body:

{
  "name": "新标题名称",
  "text": "新标题文本",
  "category": "new_category",
  "description": "新描述",
  "tags": ["新标签"]
}

响应 200 OK: 返回更新后的标题对象

---

DELETE /{title_id}

删除标题。

认证: 是

路径参数:

参数	类型	说明
title_id	string	标题 ID

响应 204 No Content

---

14. 配音库 (VoiceLibrary)

基础路径: /api/v1/voices

GET /

获取配音列表。

认证: 是

查询参数:

参数	类型	必填	说明
status	string	否	按状态筛选
skip	integer	否	跳过数量（默认 0）
limit	integer	否	返回数量（默认 50，最大 200）

响应 200 OK:

{
  "items": [
    {
      "id": "配音ID",
      "user_id": "用户ID",
      "name": "配音名称",
      "text": "配音文本",
      "voice_provider": "elevenlabs",
      "voice_id": "voice_xxx",
      "voice_name": "中文男声",
      "audio_url": "https://...",
      "duration": 10.5,
      "file_size": 102400,
      "status": "completed",
      "project_id": null,
      "tags": ["旁白"],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 20
}

---

GET /{voice_id}

获取配音详情。

认证: 是

路径参数:

参数	类型	说明
voice_id	string	配音 ID

响应 200 OK: 返回配音详情

---

POST /

创建配音。

认证: 是

请求 Body:

{
  "name": "配音名称",
  "text": "配音文本内容",
  "voice_provider": "elevenlabs",
  "voice_id": "voice_xxx",
  "voice_name": "中文男声",
  "audio_url": "https://...",
  "duration": 10.5,
  "file_size": 102400,
  "status": "completed",
  "project_id": null,
  "tags": ["旁白"]
}

字段	类型	必填	说明
name	string	是	配音名称（1-255字符）
text	string	否	配音文本
voice_provider	string	否	语音服务商
voice_id	string	否	语音 ID
voice_name	string	否	语音名称
audio_url	string	否	音频 URL
duration	float	否	时长（秒）
file_size	integer	否	文件大小
status	string	否	状态（默认 completed）
project_id	string	否	关联项目 ID
tags	array	否	标签列表

响应 201 Created: 返回创建的配音对象

---

PUT /{voice_id}

更新配音。

认证: 是

路径参数:

参数	类型	说明
voice_id	string	配音 ID

请求 Body: 同创建（所有字段可选）

响应 200 OK: 返回更新后的配音对象

---

DELETE /{voice_id}

删除配音。

认证: 是

路径参数:

参数	类型	说明
voice_id	string	配音 ID

响应 204 No Content

---

15. 查重 (Duplication)

基础路径: /api/v1/duplication

POST /upload

上传视频进行查重检测。

认证: 是

请求: multipart/form-data

字段	类型	必填	说明
file	file	是	视频文件

响应 200 OK:

{
  "id": "查重记录ID",
  "status": "pending",
  "message": "文件 \"video.mp4\" 已上传，正在查重中..."
}

限制:

• 仅支持视频文件: mp4, mpeg, mov, avi, webm, mkv, 3gp
• 最大文件大小: 100MB

---

GET /records

获取查重记录列表。

认证: 是

响应 200 OK:

[
  {
    "id": "记录ID",
    "filename": "video.mp4",
    "file_size": 5242880,
    "duration_seconds": 30.0,
    "status": "completed",
    "duplicate_rate": 0.15,
    "duplicate_count": 2,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:01:00Z"
  }
]

---

GET /records/{record_id}

获取查重记录详情（含重复片段）。

认证: 是

路径参数:

参数	类型	说明
record_id	string	查重记录 ID

响应 200 OK:

{
  "id": "记录ID",
  "filename": "video.mp4",
  "file_size": 5242880,
  "duration_seconds": 30.0,
  "status": "completed",
  "duplicate_rate": 0.15,
  "duplicate_count": 2,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:01:00Z",
  "segments": [
    {
      "id": "片段ID",
      "source_start": 5.0,
      "source_end": 10.5,
      "matched_video_id": "视频ID",
      "matched_video_name": "匹配视频名称",
      "matched_start": 0.0,
      "matched_end": 5.5,
      "similarity": 0.95
    }
  ]
}

---

DELETE /records/{record_id}

删除查重记录。

认证: 是

路径参数:

参数	类型	说明
record_id	string	查重记录 ID

响应 204 No Content

---

POST /records/{record_id}/retry

重新提交查重。

认证: 是

路径参数:

参数	类型	说明
record_id	string	查重记录 ID

响应 200 OK:

{
  "id": "记录ID",
  "status": "pending",
  "message": "已重新提交查重"
}

---

16. 订阅 (Subscription)

基础路径: /api/v1/subscription

GET /current

获取当前订阅信息。

认证: 是

响应 200 OK:

{
  "id": "sub-xxx",
  "plan_id": "pro",
  "plan_name": "专业版",
  "status": "active",
  "billing_cycle": "monthly",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-02-01T00:00:00Z",
  "amount": 299.0,
  "auto_renew": true,
  "created_at": "2024-01-01T00:00:00Z"
}

---

GET /billing-records

获取账单记录列表。

认证: 是

响应 200 OK:

[]

---

POST /change-plan

变更订阅套餐（升级/降级）。

认证: 是

请求 Body:

{
  "target_plan_id": "pro",
  "billing_cycle": "monthly"
}

字段	类型	必填	说明
target_plan_id	string	是	目标套餐: free, standard, pro, enterprise
billing_cycle	string	是	计费周期: monthly, yearly

响应 200 OK:

{
  "success": true,
  "message": "套餐已成功变更为 专业版",
  "new_subscription": { ... }
}

---

POST /cancel

取消订阅。

认证: 是

响应 200 OK:

{
  "success": true,
  "message": "订阅已取消，当前周期结束后停止服务"
}

---

POST /toggle-auto-renew

切换自动续费。

认证: 是

请求 Body:

{
  "enabled": false
}

响应 200 OK:

{
  "success": true,
  "message": "已关闭自动续费"
}

---

附录 A: 套餐配额

套餐	最大项目数	存储空间	标题库配额	配音库配额
free	3	10 GB	10 条	5 条
standard	10	50 GB	50 条	20 条
pro	无限制	100 GB	200 条	100 条
enterprise	无限制	1000 GB	无限制	无限制

---

附录 B: 套餐价格

套餐	月付	年付
free	¥0	¥0
standard	¥99	¥999
pro	¥299	¥2999
enterprise	¥999	¥9999

---

文档版本: v0.1.88 | 更新于: 2026-06-29