通用说明

本文所指的API是百度智能云向量数据库VectorDB实例的数据面API，即莫愁内核层面的API，用于操作数据库实例中的各类数据。

API调用遵循HTTP协议，每个百度智能云向量数据库VectorDB实例采用不同的域名，域名的格式为："{随机字符串}.vdb.{region}.baidubce.com"，数据交换格式为JSON，所有请求体和响应体的内容均采用UTF-8编码。

API认证机制

百度智能云向量数据库VectorDB的所有API均采用基于账号和API密钥的Bearer安全认证方式。在发送请求时，客户端在HTTP头部信息中携带账号和API密钥，均为字符串，这些信息会以HTTP头域参数的形式进行传递（HTTP头域参数格式为"Bearer account=root&api_key=eC4bLRy2va**"）。

通信协议

百度智能云向量数据库VectorDB的HTTP API当前仅支持HTTP协议，后续将支持HTTPS协议。

请求结构说明

百度智能云向量数据库VectorDB HTTP API的数据交换格式为JSON，所有请求体和响应体的内容均采用UTF-8编码。 请求参数包括如下4种：

参数类型	说明
URI	通常用于指明操作实体，如："POST /v{version}/database"
Query参数	URL中携带的请求参数
HEADER	通过HTTP头域传入的属性
RequestBody	以JSON形式表示的请求体

公共请求头

下表列出了所携带的公共头域。HTTP协议的标准头域不在此处列出。

头域（HEADER）	是否必须	说明
Authorization	是	鉴权信息，accout为帐号，api_key为密码，示例如下： "Authorization: Bearer account=root&api_key=eC4bLRy2va**"
Host	是	"{实例IP}:{实例Port}"
Content-Type	是	"application/json; charset=utf-8"
Content-Length	是	实际请求体大小
Date	否	表示日期的字符串，遵循ISO8601标准，统一使用UTC时间，日期和时间之间加字母T，结尾加字母Z表示UTC时间，如："2024-01-01T18:00:10Z" 服务端由到请求会判断本机时间与该时间差值，若大于30分钟，则抛弃本次请求，响应HTTP 400
Request-ID	否	请求的ID，非强制选项，但建议提供，并以UUID形式表示

公共响应头

下表列出了公共响应头域。HTTP协议的标准响应头域不在此处列出。

头域（HEADER）	是否必须	说明
Content-Type	是	"application/json; charset=utf-8"
Content-Length	是	实际响应体大小
Request-ID	是	对应的请求ID，若用户在请求中提供了ID，那么即为此ID，若用户未在请求中提供ID，则该ID由服务端按照UUID形式自动生成并填充。

响应结构说明

响应值分为两部分：

返回内容	说明
HTTPStatusCode	如200、400、403、404、500等
ResponseBody	以JSON格式表示的响应体

API 版本号

参数	类型	参数位置	描述	是否必须
version	String	URL参数	API版本号，当前值为1	是