Fine-tuning/标注平台对外API接口文档.md

标注平台对外 API 接口文档

版本：v1.0 更新日期：2026-05-20 基础 URL：http://{host}:{port}（部署后由标注平台提供具体地址）

---

1. 快速开始

1.1 接入流程

1. 向标注平台申请接入，获取 app_id 和 app_secret
2. 使用签名算法获取 Access Token
3. 携带 Token 调用业务接口

1.2 所有接口统一前缀

/api/v1/open

1.3 统一响应格式

所有接口返回如下 JSON 结构：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

字段	类型	说明
code	int	业务状态码，0 表示成功，非 0 表示失败
message	string	提示信息
data	object	业务数据，失败时为 null

---

2. 认证机制

2.1 凭证说明

接入标注平台后，会分配一对凭证：

字段	类型	说明
app_id	string	应用唯一标识
app_secret	string	应用密钥，仅在创建时展示一次，请妥善保存

2.2 签名算法

每次请求获取 Token 时，需使用 HMAC-SHA256 对请求参数签名：

signature = HMAC-SHA256(
    key = app_secret,
    message = app_id + timestamp + nonce
)

参数说明：

参数	说明
timestamp	当前 Unix 时间戳（秒），与服务器时间差不能超过 5 分钟
nonce	16 位随机字符串，每次请求不同，用于防重放
signature	十六进制编码的签名结果

---

3. 接口列表

序号	方法	路径	说明	认证方式
1	POST	/api/v1/open/auth/token	获取 Access Token	API Key 签名
2	POST	/api/v1/open/auth/refresh	刷新 Access Token	Bearer Token
3	GET	/api/v1/open/projects	查询项目列表	Bearer Token
4	GET	/api/v1/open/projects/{project_id}	查询项目详情	Bearer Token
5	POST	/api/v1/open/projects/{project_id}/datasets/download	数据集下载	Bearer Token
6	GET	/api/v1/open/datasets/downloads/{download_token}	获取下载文件	Bearer Token

---

4. 接口详情

4.1 获取 Access Token

请求

POST /api/v1/open/auth/token

请求头

Header	类型	必录	说明
X-Api-Key	string	是	申请的 app_id
X-Signature	string	是	HMAC-SHA256 签名（十六进制）
X-Timestamp	string	是	Unix 时间戳（秒）
X-Nonce	string	是	16 位随机字符串

请求体：无

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

错误码

HTTP 状态码	error_code	说明
401	INVALID_API_KEY	app_id 不存在
401	APP_DISABLED	应用已被禁用
401	INVALID_SIGNATURE	签名验证失败
401	TIMESTAMP_EXPIRED	时间戳过期（超过 5 分钟）
401	NONCE_USED	Nonce 已被使用

---

4.2 刷新 Access Token

请求

POST /api/v1/open/auth/refresh

请求头

Header	类型	必录	说明
Authorization	string	是	Bearer {access_token}

请求体：无

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

---

4.3 查询项目列表

请求

GET /api/v1/open/projects

请求头

Header	类型	必录	说明
Authorization	string	是	Bearer {access_token}

查询参数

参数	类型	必录	说明
name	string	否	项目名称（模糊匹配）
type	string	否	项目类型：image（图片）/ text（文本）
status	string	否	项目状态筛选
page	int	否	页码，默认 1
page_size	int	否	每页数量，默认 20，最大 100

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "project_id": "proj_abc123def456",
        "project_name": "商品图片分类标注",
        "description": "对电商平台商品图片进行分类标注",
        "project_type": "image",
        "task_type": "image_classification",
        "status": "in_progress",
        "created_by": "admin",
        "created_at": "2026-05-10T10:30:00",
        "updated_at": "2026-05-15T14:20:00",
        "task_count": 500,
        "completed_task_count": 350
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

字段说明

字段	类型	说明
project_id	string	项目唯一标识
project_name	string	项目名称
description	string	项目描述
project_type	string	项目类型：image（图片）/ text（文本）
task_type	string	具体任务类型（见下方映射表）
status	string	项目状态：draft / configuring / ready / in_progress / completed
created_by	string	项目创建人用户名
created_at	string	创建时间（ISO 8601）
updated_at	string	最后更新时间（ISO 8601）
task_count	int	总任务数
completed_task_count	int	已完成任务数

任务类型映射表

task_type	project_type	说明
text_classification	text	文本分类
ner	text	命名实体识别
image_classification	image	图片分类
object_detection	image	目标检测
polygon	image	多边形标注

---

4.4 查询项目详情

请求

GET /api/v1/open/projects/{project_id}

路径参数

参数	类型	必录	说明
project_id	string	是	项目 ID

请求头

Header	类型	必录	说明
Authorization	string	是	Bearer {access_token}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "project_id": "proj_abc123def456",
    "project_name": "商品图片分类标注",
    "description": "对电商平台商品图片进行分类标注",
    "project_type": "image",
    "task_type": "image_classification",
    "status": "in_progress",
    "created_by": "admin",
    "created_at": "2026-05-10T10:30:00",
    "updated_at": "2026-05-15T14:20:00",
    "task_count": 500,
    "completed_task_count": 350,
    "assigned_task_count": 500,
    "completion_percentage": 70.0
  }
}

错误码

HTTP 状态码	error_code	说明
404	PROJECT_NOT_FOUND	项目不存在

---

4.5 数据集下载

请求

POST /api/v1/open/projects/{project_id}/datasets/download

路径参数

参数	类型	必录	说明
project_id	string	是	项目 ID

请求头

Header	类型	必录	说明
Authorization	string	是	Bearer {access_token}

请求体

参数	类型	必录	说明
format	string	是	数据集格式（见下方格式说明）
completed_only	boolean	否	是否只导出已完成的任务，默认 true

支持的数据集格式

format 值	数据类型	格式说明
alpaca	文本	Alpaca 指令微调格式
sharegpt	文本	ShareGPT 对话格式
json	图片	平台原生 JSON 格式
csv	图片	CSV 表格格式
coco	图片	COCO 目标检测格式
yolo	图片	YOLO 目标检测格式
pascal_voc	图片	PascalVOC XML 格式

请求示例

{
  "format": "coco",
  "completed_only": true
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "project_id": "proj_abc123def456",
    "format": "coco",
    "total_exported": 350,
    "file_url": "/api/v1/open/datasets/downloads/dl_abc123",
    "file_name": "proj_abc123def456_coco_20260517_143000.json",
    "file_size": 2048576,
    "expires_at": "2026-05-17T16:30:00",
    "status": "completed"
  }
}

字段说明

字段	类型	说明
project_id	string	项目 ID
format	string	导出格式
total_exported	int	导出的任务数量
file_url	string	文件下载链接（相对路径，需拼接基础 URL）
file_name	string	文件名
file_size	int	文件大小（字节）
expires_at	string	下载链接过期时间（ISO 8601），2 小时后过期
status	string	导出状态：completed / failed

错误码

HTTP 状态码	error_code	说明
400	INVALID_FORMAT	不支持的导出格式
400	FORMAT_NOT_COMPATIBLE	格式与项目类型不兼容
404	PROJECT_NOT_FOUND	项目不存在
404	NO_DATA_AVAILABLE	项目中没有可导出的数据
500	EXPORT_FAILED	导出失败

---

4.6 获取下载文件

请求

GET /api/v1/open/datasets/downloads/{download_token}

拿到 4.5 接口返回的 file_url 后，调用此接口下载实际文件。

路径参数

参数	类型	必录	说明
download_token	string	是	下载令牌（从 4.5 接口返回的 file_url 中提取）

请求头

Header	类型	必录	说明
Authorization	string	是	Bearer {access_token}

响应

• Content-Type: application/octet-stream 或对应格式的 MIME type
• Content-Disposition: attachment; filename="..."
• 响应体为实际文件内容

错误码

HTTP 状态码	error_code	说明
410	DOWNLOAD_EXPIRED	下载链接已过期
404	NOT_FOUND	下载资源不存在

---

5. 错误码汇总

5.1 通用错误码

code	error_code	HTTP 状态码	说明
0	SUCCESS	200	请求成功
1000	INTERNAL_ERROR	500	服务器内部错误
1001	INVALID_REQUEST	400	请求参数无效
1002	UNAUTHORIZED	401	未认证或认证过期

5.2 认证错误码

code	error_code	HTTP 状态码	说明
2001	INVALID_API_KEY	401	app_id 不存在
2002	APP_DISABLED	401	应用已被禁用
2003	INVALID_SIGNATURE	401	签名验证失败
2004	TIMESTAMP_EXPIRED	401	时间戳过期
2005	NONCE_USED	401	Nonce 已被使用
2006	TOKEN_EXPIRED	401	Access Token 已过期
2007	TOKEN_INVALID	401	Access Token 无效

5.3 业务错误码

code	error_code	HTTP 状态码	说明
3001	PROJECT_NOT_FOUND	404	项目不存在
3002	INVALID_FORMAT	400	不支持的导出格式
3003	FORMAT_NOT_COMPATIBLE	400	格式与项目类型不兼容
3004	NO_DATA_AVAILABLE	404	项目中没有可导出的数据
3005	EXPORT_FAILED	500	导出失败
3006	DOWNLOAD_EXPIRED	410	下载链接已过期

---

6. 调用示例

6.1 curl 示例

# 1. 获取 Token
curl -X POST http://localhost:8003/api/v1/open/auth/token \
  -H "X-Api-Key: app_id_xxx" \
  -H "X-Signature: abc123..." \
  -H "X-Timestamp: 1716000000" \
  -H "X-Nonce: a1b2c3d4e5f6g7h8"

# 2. 查询项目列表
curl -X GET "http://localhost:8003/api/v1/open/projects?page=1&page_size=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# 3. 下载数据集
curl -X POST http://localhost:8003/api/v1/open/projects/proj_xxx/datasets/download \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "completed_only": true}'

# 4. 下载文件
curl -X GET http://localhost:8003/api/v1/open/datasets/downloads/dl_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

---

7. 注意事项

1. Token 有效期：Access Token 默认 2 小时过期，过期后需重新通过签名获取
2. 下载链接有效期：数据集下载接口返回的 file_url 2 小时后过期，请及时下载
3. Nonce 唯一性：每次请求的 nonce 必须不同，重复使用会被拒绝
4. 时间同步：请求时间戳与服务器时间差不能超过 5 分钟，请确保客户端时钟准确
5. 格式兼容：文本项目只能使用 alpaca / sharegpt 格式，图片项目只能使用 json / csv / coco / yolo / pascal_voc 格式