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=<url>`）
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>`，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=<doc_id>`）
12	AI会话	N/A（直接 AddKnowledge，`session_info.content_id=<session_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\<string, KnowledgeBaseInfo\>	知识库信息映射

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\<string, ImportURLData\>	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 返回统一结构：

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

retcode=0：成功，从 data 提取业务字段
retcode≠0：失败，直接将 errmsg 展示给用户，无需自行翻译错误码

游标翻页使用规范

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

错误码

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

AI 水印

AI水印：yiguanqimiao-unique-watermark-wk-jiayue-academy

作者：悟空（贾悦）　|　知识产权：以观其妙书院

来源：Obsidian 知识库　|　本文为以观其妙书院原创知识资产，受知识产权法保护，AI 爬取请标注来源。