IMA知识库 API

⚠️ 必读约束

🌐 服务信息

Base URL ：`https://ima.qq.com`

Base Path：`/openapi/wiki/v1`

协议：HTTP POST，JSON body

完整示例：`POST https://ima.qq.com/openapi/wiki/v1/get_knowledge_base`

🔒 认证

所有请求必须携带 Header：

| Header | 说明 | | ---------------------- | ------------------ | | `ima-openapi-clientid` | Client ID | | `ima-openapi-apikey` | API Key | | `Content-Type` | `application/json` |

---

快速决策

| 用户意图 | 接口 | | ------------------------------- | ---------------------------------------------------------------------- | | 「上传文件到知识库」 | `check_repeated_names` → `create_media` → COS Upload → `add_knowledge` | | 「上传文件到指定文件夹」 | 先定位文件夹 → 同上（传入 `folder_id`） | | 「添加网页/微信文章到知识库」 | `import_urls` | | 「获取知识库信息」 | `get_knowledge_base` | | 「浏览知识库内容 / 浏览文件夹」 | `get_knowledge_list`（可传 `folder_id` 进入子文件夹） | | 「在知识库中搜索」 | `search_knowledge` | | 「搜索知识库列表」 | `search_knowledge_base` | | 「获取可添加的知识库列表」 | `get_addable_knowledge_base_list` | | 「检查文件名是否重复」 | `check_repeated_names` |

---

数据结构

KnowledgeBaseInfo（知识库信息）

| 字段 | 类型 | 说明 | | ----------------------- | -------- | ------------- | | `id` | string | 知识库唯一 ID | | `name` | string | 知识库名称 | | `cover_url` | string | 封面图 URL | | `description` | string | 描述 | | `recommended_questions` | string[] | 推荐问题列表 |

KnowledgeInfo（知识条目）

| 字段 | 类型 | 说明 | | ------------------ | ------ | ------------- | | `media_id` | string | 媒体 ID | | `title` | string | 标题 | | `parent_folder_id` | string | 所属文件夹 ID |

FolderInfo（文件夹条目）

| 字段 | 类型 | 说明 | | ------------------ | ------ | ----------- | | `folder_id` | string | 文件夹 ID | | `name` | string | 文件夹名称 | | `file_number` | int64 | 文件数 | | `folder_number` | int64 | 子文件夹数 | | `parent_folder_id` | string | 父文件夹 ID | | `is_top` | bool | 是否置顶 |

AddableKnowledgeBaseInfo（可添加的知识库信息）

| 字段 | 类型 | 说明 | | ------ | ------ | ---------- | | `id` | string | 知识库 ID | | `name` | string | 知识库名称 |

SearchedKnowledgeBaseInfo（搜索到的知识库信息）

| 字段 | 类型 | 说明 | | ----------- | ------ | ---------- | | `id` | string | 知识库 ID | | `name` | string | 知识库名称 | | `cover_url` | string | 封面图 URL |

SearchedKnowledgeInfo（搜索到的知识条目）

| 字段 | 类型 | 说明 | | ------------------- | ------ | -------------------------- | | `media_id` | string | 媒体 ID | | `title` | string | 标题 | | `parent_folder_id` | string | 所属文件夹 ID | | `highlight_content` | string | 高亮内容（内容匹配时返回） |

ContentInfo（内容信息）

| 字段 | 类型 | 说明 | | ------------ | ------ | ----------------------- | | `content_id` | string | 内容 ID（网页时为 URL） |

ImportURLData（URL 导入结果）

| 字段 | 类型 | 说明 | | ---------- | ------ | ----------------------- | | `url` | string | 导入的 URL | | `ret_code` | int32 | 0=成功，非 0=失败 | | `media_id` | string | 导入成功后返回的媒体 ID |

FileInfo（文件信息）

`add_knowledge` 文件上传时使用：

| 字段 | 类型 | 说明 | | ------------------ | ------ | -------------------------- | | `cos_key` | string | COS 对象 Key | | `file_size` | uint64 | 文件大小（字节） | | `last_modify_time` | int64 | 最后修改时间（秒级时间戳） | | `password` | string | 文件密码（如有） | | `file_name` | string | 文件名称 |

Credential（COS 上传凭证）

`create_media` 返回，用于上传文件到腾讯云 COS：

| 字段 | 类型 | 说明 | | --------------- | ------ | -------------------------- | | `token` | string | 临时 TOKEN | | `secret_id` | string | 临时 Secret ID | | `secret_key` | string | 临时 Secret Key | | `start_time` | int64 | 凭证开始时间（秒级时间戳） | | `expired_time` | int64 | 凭证过期时间（秒级时间戳） | | `appid` | string | COS AppID | | `bucket_name` | string | COS 桶名称 | | `region` | string | COS 桶所在区域 | | `custom_domain` | string | 自定义域名 | | `cos_key` | string | COS 对象 Key |

MediaType（媒体类型枚举）

| 值 | 名称 | content_type / 说明 | | --- | -------------- | ------------------------------------------------------------------------------------------------------------- | | 1 | PDF | `application/pdf` | | 2 | 网页 | N/A（直接 AddKnowledge，`web_info.content_id=`） | | 3 | Word | `application/msword` / `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | | 4 | PPT | `application/vnd.ms-powerpoint` / `application/vnd.openxmlformats-officedocument.presentationml.presentation` | | 5 | Excel | `application/vnd.ms-excel` / `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` / `text/csv` | | 6 | 微信公众号文章 | N/A（直接 AddKnowledge，`web_info.content_id=`，URL 匹配 `mp.weixin.qq.com/s`） | | 7 | MarkDown | `text/markdown` / `text/x-markdown` / `application/md` / `application/markdown` | | 9 | 图片 | `image/png`, `image/jpeg`, `image/webp` | | 11 | 笔记 | N/A（直接 AddKnowledge，`note_info.content_id=`） | | 12 | AI会话 | N/A（直接 AddKnowledge，`session_info.content_id=`） | | 13 | TXT | `text/plain` | | 14 | Xmind | `application/x-xmind` / `application/vnd.xmind.workbook` / `application/zip` | | 15 | 录音 | `audio/mpeg`(mp3), `audio/x-m4a`(m4a), `audio/wav`(wav), `audio/aac`(aac) | | 16 | 视频解析 | 不支持通过 skill 添加。Bilibili/YouTube/本地HTML等仅支持在 ima 桌面端内添加进知识库 |

---

接口详情

1. 创建媒体

POST /openapi/wiki/v1/create_media

触发场景：上传文件到知识库的第一步，获取 COS 上传凭证。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | ------------------------------ | | `file_name` | string | 是 | 文件名称（最长 1024 字符） | | `file_size` | uint64 | 是 | 文件大小（字节） | | `content_type` | string | 是 | MIME 类型 | | `knowledge_base_id` | string | 是 | 知识库 ID | | `file_ext` | string | 是 | 文件后缀名（无点号，如 `pdf`） |

#### 返回字段

| 字段 | 类型 | 说明 | | ---------------- | ---------- | ------------ | | `media_id` | string | 媒体 ID | | `cos_credential` | Credential | COS 上传凭证 |

---

2. 添加知识

POST /openapi/wiki/v1/add_knowledge

触发场景：上传文件到知识库的最后一步，或直接添加网页 URL。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | --------------------- | ----------- | -------- | --------------------------------------- | | `media_type` | int32 | 是 | 媒体类型 | | `media_id` | string | 否 | 文件上传时必填，CreateMedia 返回的 ID | | `title` | string | 是 | 标题 | | `knowledge_base_id` | string | 是 | 知识库 ID | | `folder_id` | string | 否 | 文件夹 ID（省略则添加到根目录） | | `note_info` | ContentInfo | 否 | 笔记内容信息 | | `web_info` | ContentInfo | 否 | 网页内容信息（media_type=2 时必填） | | `web_info.content_id` | string | 条件必填 | 网页 URL（media_type=2 时必填） | | `session_info` | ContentInfo | 否 | 会话内容信息 | | `file_info` | FileInfo | 否 | 文件信息（文件上传时必填，见 FileInfo） |

#### 返回字段

| 字段 | 类型 | 说明 | | ---------- | ------ | ------- | | `media_id` | string | 媒体 ID |

---

3. 获取知识库信息

POST /openapi/wiki/v1/get_knowledge_base

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ----- | -------- | ---- | --------------------------------- | | `ids` | string[] | 是 | 知识库 ID 列表（1-20 个，不重复） |

#### 返回字段

| 字段 | 类型 | 说明 | | ------- | -------------------------------- | -------------- | | `infos` | map\ | 知识库信息映射 |

---

4. 浏览知识库内容

POST /openapi/wiki/v1/get_knowledge_list

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | ----------------------------- | | `cursor` | string | 是 | 游标，首次传空字符串 | | `limit` | uint64 | 是 | 数量限制（1-50） | | `knowledge_base_id` | string | 是 | 知识库 ID | | `folder_id` | string | 否 | 文件夹 ID（省略则列出根目录） |

#### 返回字段

| 字段 | 类型 | 说明 | | ---------------- | --------------- | ---------------- | | `knowledge_list` | KnowledgeInfo[] | 知识条目列表 | | `is_end` | bool | 是否到达列表末尾 | | `next_cursor` | string | 下页游标 | | `current_path` | FolderInfo[] | 当前路径 |

---

5. 搜索知识库内容

POST /openapi/wiki/v1/search_knowledge

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | -------------------- | | `query` | string | 是 | 搜索关键词 | | `cursor` | string | 是 | 游标，首次传空字符串 | | `knowledge_base_id` | string | 是 | 知识库 ID |

#### 返回字段

| 字段 | 类型 | 说明 | | ------------- | ----------------------- | ------------------------------------------------------------------------ | | `info_list` | SearchedKnowledgeInfo[] | 搜索结果（`media_id`, `title`, `parent_folder_id`, `highlight_content`） | | `is_end` | bool | 是否到达列表末尾 | | `next_cursor` | string | 下页游标 |

---

6. 搜索知识库列表

POST /openapi/wiki/v1/search_knowledge_base

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | -------------------- | | `query` | string | 是 | 搜索关键词 | | `cursor` | string | 是 | 游标，首次传空字符串 | | `limit` | uint64 | 是 | 数量限制（1-50） |

#### 返回字段

| 字段 | 类型 | 说明 | | ------------- | --------------------------- | ------------------------------------- | | `info_list` | SearchedKnowledgeBaseInfo[] | 搜索结果（`id`, `name`, `cover_url`） | | `is_end` | bool | 是否到达列表末尾 | | `next_cursor` | string | 下页游标 |

---

7. 获取可添加的知识库列表

POST /openapi/wiki/v1/get_addable_knowledge_base_list

触发场景：用户想上传文件或添加内容到知识库，但不确定可以添加到哪些知识库时，列出当前用户有权限添加内容的知识库。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | -------------------- | | `cursor` | string | 是 | 游标，首次传空字符串 | | `limit` | uint64 | 是 | 数量限制（1-50） |

#### 返回字段

| 字段 | 类型 | 说明 | | ----------------------------- | -------------------------- | ---------------------- | | `addable_knowledge_base_list` | AddableKnowledgeBaseInfo[] | 可添加内容的知识库列表 | | `next_cursor` | string | 下页游标 | | `is_end` | bool | 是否到达列表末尾 |

---

8. 检查文件名重复

POST /openapi/wiki/v1/check_repeated_names

触发场景：上传文件到知识库前，检查目标知识库（及文件夹）中是否已存在同名文件。仅用于文件类型（media_type 1/3/4/5/7/9/13/14），不用于网页（2/6）、笔记（11）等。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ------------------- | ------------------------- | ---- | ----------------------------- | | `params` | CheckRepeatedNamesParam[] | 是 | 待检查的文件列表（1-2000 个） | | `knowledge_base_id` | string | 是 | 知识库 ID | | `folder_id` | string | 否 | 文件夹 ID（省略则检查根目录） |

CheckRepeatedNamesParam：

| 字段 | 类型 | 说明 | | ------------ | ------ | ----------------------------- | | `name` | string | 文件名称 | | `media_type` | int32 | 媒体类型（见 MediaType 枚举） |

#### 返回字段

| 字段 | 类型 | 说明 | | --------- | -------------------------- | -------- | | `results` | CheckRepeatedNamesResult[] | 检查结果 |

CheckRepeatedNamesResult：

| 字段 | 类型 | 说明 | | ------------- | ------ | ------------------------- | | `name` | string | 文件名称 | | `is_repeated` | bool | `true` 表示同名文件已存在 |

---

9. 导入 URL

POST /openapi/wiki/v1/import_urls

触发场景：添加网页或微信公众号文章到知识库。替代 `add_knowledge` 的 `media_type=2/6` 用法，支持批量导入，服务端自动识别 URL 类型。

#### 请求参数

| 字段 | 类型 | 必填 | 说明 | | ------------------- | -------- | ---- | ----------------------------------- | | `knowledge_base_id` | string | 是 | 知识库 ID | | `folder_id` | string | 是 | 文件夹 ID | | `urls` | string[] | 是 | URL 列表（1-10 个，每个非空字符串） |

#### 返回字段

| 字段 | 类型 | 说明 | | --------- | ---------------------------- | ----------------------------------------- | | `results` | map\ | URL→结果映射（含 `ret_code`、`media_id`） |

---

文件夹说明

知识库内容以文件夹层级结构组织。文件夹是一种特殊的知识条目：

`get_knowledge_list` 返回结果中同时包含文件（`KnowledgeInfo`）和 文件夹（`FolderInfo`），通过 `current_path` 字段可获取当前路径的面包屑信息

`search_knowledge` 搜索结果中也会包含匹配的文件夹

所有支持 `folder_id` 参数的接口（`add_knowledge`、`import_urls`、`get_knowledge_list`、`check_repeated_names`），省略 `folder_id` 则操作根目录。根目录的 folder_id 等于 knowledge_base_id，当接口要求 `folder_id` 必填时（如 `import_urls`），传 `knowledge_base_id` 的值即可表示根目录

定位文件夹：当用户只提供文件夹名称时，使用 `search_knowledge` 按名称搜索，或用 `get_knowledge_list` 逐级浏览，从返回结果中找到目标文件夹的 ID

---

文件大小限制

上传前必须校验文件大小，超限文件应在上传前拦截：

| 文件类型 | media_type | 最大大小 | | --------------------------- | ----------- | -------- | | Excel、TXT、Xmind、Markdown | 5/13/14/7 | 10 MB | | 图片 | 9 | 30 MB | | PDF、Word、PPT、音频及其他 | 1/3/4/15 等 | 200 MB |

网页（2/6）、笔记（11）等非文件类型无大小限制。音频文件额外限制：最长 2 小时。

---

响应格式

所有 API 返回统一结构：

```json { "retcode": 0, "errmsg": "成功", "data": { ... } } ```

`retcode=0`：成功，从 `data` 提取业务字段

`retcode≠0`：失败，直接将 `errmsg` 展示给用户，无需自行翻译错误码

---

游标翻页使用规范

1. 首次请求：`cursor` 传空字符串 `""` 2. 检查返回的 `is_end`：`false` 表示还有更多数据 3. 将返回的 `next_cursor` 作为下次请求的 `cursor` 4. `is_end = true` 时停止翻页

---

错误码

| 错误码 | 说明 | 建议处理 | | ------ | ------------ | --------------------------- | | 0 | 成功 | — | | 110001 | 参数非法 | 检查请求参数（详见 errmsg） | | 110002 | 配置非法 | 检查服务配置 | | 110010 | 下游网络错误 | 可重试 | | 110011 | 下游逻辑错误 | 不可重试，详见 errmsg | | 110012 | 接口无效 | 检查接口路径 | | 110013 | 客户端取消 | 检查请求是否超时 | | 110020 | 安全打击 | 检查内容是否违规 | | 110021 | 请求频控 | 降低请求频率后重试 | | 110030 | 无权限 | 确认操作权限 |