一、服务地址
V3 API 的服务地址为：
https://memory.tdai.tencentyun.com
所有 V3 接口均以此为基地址，拼接路径即得完整 URL。例如：
POST https://memory.tdai.tencentyun.com/v3/conversation/addPOST https://memory.tdai.tencentyun.com/v3/atomic/search
二、通信协议
V3 API 仅支持 HTTPS 协议，不支持 HTTP 明文传输。
三、请求方法
所有 V3 API 均使用 POST 方法。请求体（Request Body）统一使用 JSON 格式。
四、请求头
每次请求需携带以下 HTTP 头：
| 请求头 | 必填 | 说明 |
| Content-Type | 是 | 固定为 application/json |
| Authorization | 是 | 格式为 Bearer <API Key>，API Key 在控制台「API 接入信息」页面获取 |
| x-tdai-service-id | 是 | Memory 实例 ID，格式为 tdai-mem-xxxxxxxx，在控制台实例详情页获取 |
| x-tdai-user-id | 否 | 操作人用户标识，数据类型 String。传入后将记录到对应接口的审计字段（如 created_by、updated_by、operator_id），便于审计追踪 |
| x-request-id | 否 | 请求唯一标识，数据类型 String。由调用方生成；若不传，系统自动分配。可用于日志关联与问题排查 |
五、鉴权方式
V3 API 采用 API Key 鉴权。鉴权失败时服务端返回 401 Unauthorized 或业务 code 非 0 的错误响应。
获取 API Key：登录 Memory 控制台，进入目标实例详情页，在「API 接入信息」区域查看或复制 API Key。
六、鉴权请求示例
curl -i -k -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer *********************************' \\ -H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\ https://memory.tdai.tencentyun.com/v3/conversation/add \\ -d '{ "session_id":"agent-main:sess-001", "messages":[ {"role":"user","content":"你好"} ] }'
七、参数类型
V3 API 参数采用以下数据类型：
| 类型 | 说明 |
| String | 字符串 |
| Integer | 整数 |
| Array | JSON 数组 |
| Object | JSON 对象 |
八、字符编码
所有请求与响应均使用 UTF-8 字符编码。