创建上传会话

接口说明

开始一次可续传上传，并返回会话标识、单次文件登记上限和建议上传并发数。

接口信息

字段	值
方法	POST
路径	/openapi/v2/knowledge-bases/{knowledgeBaseId}/upload-sessions
Operation ID	createUploadSession
鉴权	Bearer OpenAPI key

入参

名称	位置	必填	类型	示例	说明
knowledgeBaseId	path	是	string	knowledge-base-11111111-1111-4111-8111-111111111111	知识库 API 返回的知识库标识。
Idempotency-Key	header	是	string	mutation-2026-07-10-001	客户端为请求生成的幂等键。重试同一请求时复用相同值，可以避免创建重复任务。

请求体

application/json

字段	必填	类型	示例	说明
declaredFileCount	是	integer	1	本次上传声明的文件总数。
declaredByteCount	是	integer	37	本次上传声明的总字节数。

请求示例

curl -X POST "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/upload-sessions" \
  -H "Authorization: Bearer <openapi-key>" \
  -H "Idempotency-Key: mutation-2026-07-10-001" \
  -H "Content-Type: application/json" \
  --data '{
  "declaredFileCount": 1,
  "declaredByteCount": 37
}'

成功响应

201

返回新上传会话、单次文件登记上限和建议正文上传并发数。

字段	必填	类型	说明
session	是	object	当前上传会话记录。
transport	是	object	创建上传会话时返回的单次文件登记上限和建议正文上传并发数。

成功响应示例

{
  "session": {
    "id": "upload-11111111-1111-4111-8111-111111111111",
    "operationId": "upload-operation-11111111-1111-4111-8111-111111111111",
    "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
    "state": "draft",
    "declaredFileCount": 1,
    "declaredByteCount": 37,
    "counts": {
      "selected": 0,
      "uploadRequired": 0,
      "skippedExisting": 0,
      "waitingReservation": 0,
      "rejectedDeleting": 0,
      "uploaded": 0,
      "finalized": 0
    },
    "errorCode": null,
    "expiresAt": "2026-06-18T00:00:00.000Z",
    "completedAt": null,
    "createdAt": "2026-06-17T00:00:00.000Z",
    "updatedAt": "2026-06-17T00:00:00.000Z",
    "actions": {
      "operation": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/operations/upload-operation-11111111-1111-4111-8111-111111111111"
    }
  },
  "transport": {
    "manifestPageSize": 500,
    "contentUploadConcurrency": 8
  }
}

错误码

下表列出这个接口已声明的全部错误响应。

HTTP 状态	错误码	说明
401	UNAUTHORIZED	Bearer API key 缺失、格式错误、未知、已撤销或已删除。
404	NOT_FOUND	请求的资源不存在。
409	CONFLICT	请求与资源当前状态冲突。
413	PAYLOAD_TOO_LARGE	请求体或待读取文件超过当前接口允许的大小。
422	VALIDATION_ERROR	请求未通过校验。
429	RATE_LIMITED	请求超过当前配置的速率限制。
500	INTERNAL_ERROR	API 遇到内部错误。
503	DATABASE_REPOSITORY_UNAVAILABLE	当前接口所需的数据暂时不可用。

后续操作

• 添加上传文件
• 获取上传会话