快速开始
1
注册并登录
手机号即可注册登录,登录后自动进入控制台。
2
创建 API Key
在控制台「API Keys」页面创建专属密钥,这是调用所有接口的唯一凭证。
3
发起第一个请求
将 API Key 放入 Header,调用任意端点即可——也可以先在体验中心在线调试。
cURL 示例(Server URL 加载中...)
curl -X POST /api/medgraph/search \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"entity_one_type":"Gene","entity_one_name":"TP53","entity_two_type":"Disease","entity_two_name":"Lung Cancer","relation_type":["-1"]}'
鉴权方式
所有 API 请求需在 HTTP Header 中携带 Bearer Token。API Key 在控制台「API Keys」页创建和管理,可创建多组密钥区分项目或环境。
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
安全提示:API Key 是访问服务的唯一凭证,请妥善保管。如怀疑泄露,请立即在控制台删除并重新创建。鉴权失败的请求完全不计费,请放心。
端点列表
全部端点均为 POST + JSON 请求体,统一走平台 relay 路由(相对本站域名)。搜索类接口为异步任务:提交后轮询/status 至 completed,再用 result_id 取详情。
| 方法 | 端点 | 说明 | Credits |
|---|
| POST | /api/medgraph/search | 提交直接关系(1-hop)搜索,返回 task_id 供轮询 | 11 |
| POST | /api/medgraph/search-indirect | 提交多跳路径搜索,发现实体间的间接关联路径 | 11 |
| POST | /api/medgraph/resolve | 将实体别名解析为标准 entity_id,支持别名 / 缩写映射 | 11 |
| POST | /api/medgraph/status | 轮询异步搜索任务的执行状态 | 1 |
| POST | /api/medgraph/details | 分页获取直接关系搜索的完整结果(支持 result_id 复用) | 1+条目数 |
| POST | /api/medgraph/details-indirect | 分页获取多跳路径搜索的完整路径详情 | 1+跳数之和 |
| POST | /api/medgraph/evidences | 获取指定关系的文献证据列表 | 1+证据条数×10 |
| POST | /api/medgraph/evidences-indirect | 获取多跳路径中每一跳的文献证据 | 1+证据条数×10 |
POST /api/medgraph/search — 直接关系搜索(1-hop)
提交两个实体与关系类型,返回二者之间的直接关系及概率分。异步接口:先返回 task_id,轮询 /status 至 completed 后用 result_id 调 /details 取结果。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| entity_one_type | string | 是 | 实体类型:Gene, Chemical, Disease, Species, Anatomy, Biological Process, CellLine, Cellular Component, DNAMutation, Molecular Function, Pathway, Pharmacologic Class |
| entity_one_name | string | 否 | 实体一名称,如 TP53 |
| entity_two_type | string | 否 | 实体二类型,缺省 Gene;可只传类型不传名称做全类型扫描 |
| entity_two_name | string | 否 | 实体二名称 |
| relation_type | string[] | 是 | 关系类型列表,传 ["-1"] 表示不过滤 |
| probability_threshold | number | 否 | 概率下限,默认 0.85 |
| prob_method | string | 否 | 概率来源:MP=文本挖掘 / MA=人工注释 / RNASeq=表达量 |
| novelty | string | 否 | '1' 仅新颖边,'0' 仅非新颖边(过滤会剔除人工注释边) |
| start_date / end_date | string | 否 | 证据发表日期区间 YYYY-MM-DD(过滤会剔除人工注释边) |
| relation_direction | string | 否 | '12' / '21' / '0' / 'NA',方向敏感问题时使用 |
| correlation_type | string[] | 否 | 相关性:'2' 正相关 / '0' 负相关 / '1' 极性未知 |
| enforce_refetch | string | 否 | "1" 绕过缓存强制重算 |
请求示例
{
"entity_one_type": "Gene",
"entity_one_name": "TP53",
"entity_two_type": "Disease",
"entity_two_name": "Lung Cancer",
"relation_type": [
"-1"
],
"probability_threshold": 0.85
}
响应示例
{
"status": "success",
"message": "Your search request has been queued. Please poll the status endpoint with your task_id.",
"task_id": "2748b9d8-2bb6-4f93-aedf-cbb06c90a879",
"platform_credits_consumed": 11,
"platform_credits_remaining": 99989
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | 请求受理结果:成功排队固定返回 "success" |
| message | string | 排队提示:任务已创建,需用 task_id 轮询 /status |
| task_id | string | 异步任务 ID,48 小时内有效;轮询 /status 至 completed 后换取 result_id |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:缓存提示:同一用户 5 分钟内完全相同的请求体命中平台缓存,返回相同 task_id 且仅扣 1 credit。需要强制重算时在请求体加入 enforce_refetch: "1"。
POST /api/medgraph/search-indirect — 间接路径搜索(多跳)
搜索两实体之间经中间节点的间接路径(X → 中间体 → Y),适合机制链、药物重定位、靶点通路等问题。实体类型仅支持 Chemical / Disease / Gene。异步接口,流程同 /search。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| entity_one_type | string | 是 | 仅支持 Chemical / Disease / Gene |
| entity_one_name | string | 是 | 实体一名称 |
| entity_two_type | string | 否 | 同上三类,缺省 Gene |
| entity_two_name | string | 是 | 实体二名称 |
| intermediate_nodes | number | 否 | 中间节点数上限,默认 1,最大 2(更深层成本陡增) |
| novelty | string | 否 | '1' 仅新颖路径,'0' 仅非新颖(过滤会剔除含人工注释跳的路径) |
| starting_date / ending_date | string | 否 | 证据发表日期区间 YYYY-MM-DD(注意本端点字段名带 -ing) |
| direction | string | 否 | '12' 或 '21'(本端点仅支持这两个值) |
| enforce_refetch | string | 否 | "1" 绕过缓存强制重算 |
请求示例
{
"entity_one_type": "Chemical",
"entity_one_name": "Aspirin",
"entity_two_type": "Disease",
"entity_two_name": "Alzheimer's Disease",
"intermediate_nodes": 1
}
响应示例
{
"status": "success",
"message": "Your indirect search request has been queued. Please poll the status endpoint with your task_id.",
"task_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"platform_credits_consumed": 11,
"platform_credits_remaining": 99989
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | 请求受理结果:成功排队固定返回 "success" |
| message | string | 排队提示:任务已创建,需用 task_id 轮询 /status |
| task_id | string | 异步任务 ID,48 小时内有效;轮询 /status 至 completed 后换取 result_id |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:中间节点越多计算量越大(成本陡增),建议从 intermediate_nodes = 1 开始。缓存规则同 /search:5 分钟内相同请求体仅扣 1 credit。
POST /api/medgraph/resolve — 实体解析
校验实体是否存在于知识图谱,返回标准 entity_id 与已知别名。搜索结果为空时先用本接口排查实体名拼写,再用别名重试。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| entity_type | string | 是 | 实体类型:Gene, Chemical, Disease, Species, Anatomy, Biological Process, CellLine, Cellular Component, DNAMutation, Molecular Function, Pathway, Pharmacologic Class |
| entity_name | string | 是 | 实体名称 |
| entity_species | string | 否 | 物种上下文,如 human、mouse(影响基因解析) |
| is_drug | string | 否 | "1" 限定药物子类,仅 entity_type 为 Chemical / Gene 时有效 |
请求示例
{
"entity_type": "Gene",
"entity_name": "TP53"
}
响应示例
{
"status": "success",
"entity_id": "7157",
"entity_type": "Gene",
"entity_name": "TP53",
"entity_species": "Homo Sapiens",
"platform_credits_consumed": 11,
"platform_credits_remaining": 99989
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | "success" 表示实体在图谱中命中 |
| entity_id | string | 图谱标准实体 ID(biokdeid),搜索接口内部即按此 ID 定位节点 |
| entity_type | string | 回显:实体类型 |
| entity_name | string | 回显:实体名称 |
| entity_species | string | 回显:物种上下文 |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:未命中返回 HTTP 404 {"error": "Entity not found: ..."},不计费。名称按 officialName → commonName → 大小写不敏感 officialName 级联匹配;搜索无结果时可先用本接口排查拼写。
POST /api/medgraph/status — 任务状态查询
轮询异步搜索任务的状态。status 为 completed 后从响应取 result_id,调 /details 或 /details-indirect 获取结果。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| task_id | string | 是 | 搜索接口返回的任务 ID |
请求示例
{
"task_id": "<搜索接口返回的 task_id>"
}
响应示例
{
"status": "completed",
"task_id": "2748b9d8-2bb6-4f93-aedf-cbb06c90a879",
"search_type": "direct",
"created_at": "2026-03-16T10:30:00",
"result_id": "69b3200a04bac13dfd4f45a5",
"relations_count": 117,
"message": "Search completed. Use the result_id to retrieve details.",
"platform_credits_consumed": 1,
"platform_credits_remaining": 99988
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | 任务状态:pending 排队中 / running 执行中 / completed 已完成 / failed 失败 |
| task_id | string | 回显:任务 ID |
| search_type | string | 任务类型:direct 直接搜索 / indirect 间接搜索 |
| created_at | string | 任务提交时间(ISO 8601) |
| result_id | string | 仅 completed 返回:结果 ID,永久有效,用于 /details、/details-indirect 与证据接口 |
| relations_count | number | 仅 direct 任务完成时返回:关系总条数 |
| paths_count | number | 仅 indirect 任务完成时返回:路径总条数 |
| error | string | 仅 failed 返回:失败原因 |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:task_id 48 小时后过期(轮询返回 404);result_id 永久有效,拿到后请立即保存。同一 task_id 轮询间隔需 ≥1 秒(建议 ≥3 秒),过密返回 429 且不计费。
POST /api/medgraph/details — 直接关系结果详情
获取已完成直接搜索任务的关系列表(含概率分)。每条关系带 relID,可调 /evidences 获取文献证据。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| result_id | string | 是 | 任务完成后返回的结果 ID |
| requested_relations_count | number | 否 | 拉取关系条数,默认 20(计费与条数成正比,建议一次拉足) |
请求示例
{
"result_id": "<status 返回的 result_id>",
"requested_relations_count": 20
}
响应示例
{
"relations_count": 117,
"returned_count": 20,
"relations": [
{
"relID": "647681.4744.3.0.12.MP",
"probability": "1.0",
"relation_details": {
"node1Id": "4744",
"node1Name": "Lung Cancer",
"node1Type": "Disease",
"node2Id": "647681",
"node2Name": "Docetaxel",
"node2Type": "Chemical",
"score": 43.697,
"relationship_type": "Negative_Correlation",
"correlation_type": "0",
"direction": "21"
},
"evidence_count": 5,
"relation_seq_id": 1
}
],
"platform_credits_consumed": 21,
"platform_credits_remaining": 99968
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| relations_count | number | 该结果的关系总条数 |
| returned_count | number | 本次实际返回条数(受 requested_relations_count 限制) |
| relations | array | 关系列表,按 probability 降序;疾病亚型展开时按亚型分组(含 disease_name 字段) |
| relations[].relID | string | 关系唯一标识(编码实体 ID、关系类型、方向、来源),调 /evidences 时原样传入 |
| relations[].probability | string | 关系概率分(0~1),越高越可信 |
| relations[].relation_details | object | 关系元数据(嵌套字段见下) |
| relation_details.node1Id / node1Name / node1Type | string | 实体一的图谱 ID / 显示名 / 类型 |
| relation_details.node2Id / node2Name / node2Type | string | 实体二的图谱 ID / 显示名 / 类型 |
| relation_details.score | number | 关系置信分 |
| relation_details.relationship_type | string | 关系类型,如 Positive_Correlation、Association、treats |
| relation_details.correlation_type | string | 相关性:"2" 正相关 / "0" 负相关 / "1" 极性未知 |
| relation_details.direction | string | 方向:"12" 实体一→实体二 / "21" 反向 / "0"、"NA" 无方向 |
| relations[].evidence_count | number | 该关系的文献证据条数;0 表示人工注释关系(无文献证据) |
| relations[].relation_seq_id | number | 结果内序号 |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:计费说明:消耗 = 1(基础费)+ 返回关系条目数。result_id 永久有效,重复查看同一结果建议复用 result_id 而非重新搜索。
POST /api/medgraph/details-indirect — 间接路径结果详情
获取已完成间接搜索任务的路径列表(X → 中间体 → Y)。每跳关系带 relID,可调 /evidences-indirect 获取证据。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| result_id | string | 是 | 任务完成后返回的结果 ID |
| requested_paths_count | number | 否 | 拉取路径条数,默认 20(计费与条数成正比,建议一次拉足) |
请求示例
{
"result_id": "<status 返回的 result_id>",
"requested_paths_count": 20
}
响应示例
{
"paths_count": 42,
"returned_count": 10,
"paths": [
{
"path_length": 2,
"net_correlationType": "Positive_Correlation",
"net_prob": 0.85,
"nodes": [
{ "entity_id": "7529", "name": "GSTK1", "officialName": "GSTK1", "commonName": "GST", "type": "Gene" },
{ "entity_id": "12345", "name": "RPS6KB1", "officialName": "RPS6KB1", "commonName": "S6K1", "type": "Gene" },
{ "entity_id": "2438", "name": "Prostatic Neoplasms", "officialName": "Prostatic Neoplasms", "commonName": "Prostatic Carcinoma", "type": "Disease" }
],
"relationships": [
{ "relID": "7529.12345.30.1.NA.primeKG", "relationshipType": "Association", "correlationType": "Positive_Correlation", "direction": "NA", "score": 1.0, "prob": 0.95, "evidence_count": 0 },
{ "relID": "12345.2438.27.1.NA.MP", "relationshipType": "Association", "correlationType": "Positive_Correlation", "direction": "NA", "score": 1.0, "prob": 0.89, "evidence_count": 8 }
]
}
],
"platform_credits_consumed": 21,
"platform_credits_remaining": 99968
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| paths_count | number | 该结果的路径总条数 |
| returned_count | number | 本次实际返回路径数(受 requested_paths_count 限制) |
| paths | array | 路径列表,按 net_prob(净概率)降序 |
| paths[].path_length | number | 路径跳数(节点数 - 1) |
| paths[].net_correlationType | string | 全路径净相关性:Positive_Correlation / Negative_Correlation |
| paths[].net_prob | number | 路径净概率(各跳概率连乘),越高越可信 |
| paths[].nodes | array | 有序节点列表(起点 → 中间节点 → 终点) |
| nodes[].entity_id | string | 节点的图谱标准 ID |
| nodes[].name | string | 显示名(officialName 或 commonName) |
| nodes[].officialName / commonName | string | 官方名 / 通用名 |
| nodes[].type | string | 实体类型(Gene / Disease / Chemical) |
| paths[].relationships | array | 路径上的关系列表,每跳一个 |
| relationships[].relID | string | 该跳关系 ID,调 /evidences-indirect 取文献证据时传入 |
| relationships[].relationshipType | string | 关系类型,如 Association |
| relationships[].correlationType | string | 相关性:Positive_Correlation / Negative_Correlation |
| relationships[].direction | string | 方向:"12" / "21" / "NA" / "0" |
| relationships[].score | number | 关系置信分 |
| relationships[].prob | number | 该跳关系概率(0~1) |
| relationships[].evidence_count | number | 该跳的文献证据条数;0 表示人工注释(无证据) |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:计费说明:消耗 = 1(基础费)+ 返回路径的总跳数(一条 2 跳路径计 2 条关系)。每跳 relID 可独立调 /evidences-indirect 取证据。
POST /api/medgraph/evidences — 直接关系证据
获取某条直接关系的文献证据。relID 来自 /details 的返回。引用证据 ID 时请逐字复制,禁止编造。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| result_id | string | 是 | 结果 ID |
| relID | string | 是 | 关系 ID(来自 /details 返回) |
| page | number | 否 | 页码,默认 1 |
| page_size | number | 否 | 每页条数,默认 20 |
请求示例
{
"result_id": "<result_id>",
"relID": "<details 返回的 relID>",
"page": 1,
"page_size": 20
}
响应示例
{
"status": "success",
"result_id": "69b3200a04bac13dfd4f45a5",
"relID": "647681.4744.3.0.12.MP",
"total_count": 61,
"page": 1,
"page_size": 20,
"total_pages": 4,
"evidences": [
{ "pmid": "15160349", "probability": 0.98, "pub_date": "2004-05-01" },
{ "pmid": "18294837", "probability": 0.95, "pub_date": "2008-02-15" }
],
"platform_credits_consumed": 21,
"platform_credits_remaining": 99947
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | "success" 表示查询成功 |
| result_id | string | 回显:结果 ID |
| relID | string | 回显:关系 ID |
| total_count | number | 该关系的文献证据总条数(按证据去重);人工注释关系恒为 0 |
| page | number | 当前页码(从 1 开始) |
| page_size | number | 每页条数(1~500) |
| total_pages | number | 总页数 |
| evidences | array | 当前页证据列表,按 probability 降序 |
| evidences[].pmid | string | 证据 ID(引用时请逐字复制,禁止编造) |
| evidences[].probability | number | 该证据支持此关系的最高句级概率(0~1) |
| evidences[].pub_date | string | 文献发表日期(YYYY-MM-DD) |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:人工注释(curated)关系没有文献抽取证据,evidences 恒为 [] 且仅收基础费。证据按最高句级概率排序,同一证据只出现一次。
POST /api/medgraph/evidences-indirect — 间接路径证据
获取间接路径中某跳关系的文献证据。relID 来自 /details-indirect 的返回。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
| result_id | string | 是 | 结果 ID |
| relID | string | 是 | 关系 ID(来自 /details-indirect 返回) |
| page | number | 否 | 页码,默认 1 |
| page_size | number | 否 | 每页条数,默认 20 |
请求示例
{
"result_id": "<result_id>",
"relID": "<details-indirect 返回的 relID>",
"page": 1,
"page_size": 20
}
响应示例
{
"status": "success",
"result_id": "69c4311b15cbc24ege5f56b6",
"relID": "12345.2438.27.1.NA.MP",
"total_count": 12,
"page": 1,
"page_size": 20,
"total_pages": 1,
"evidences": [
{ "pmid": "28651234", "probability": 0.97, "pub_date": "2017-04-12" },
{ "pmid": "31045678", "probability": 0.89, "pub_date": "2019-05-08" }
],
"platform_credits_consumed": 21,
"platform_credits_remaining": 99947
}
响应参数
| 字段 | 类型 | 说明 |
|---|
| status | string | "success" 表示查询成功 |
| result_id | string | 回显:结果 ID |
| relID | string | 回显:关系 ID |
| total_count | number | 该关系的文献证据总条数(按证据去重);人工注释关系恒为 0 |
| page | number | 当前页码(从 1 开始) |
| page_size | number | 每页条数(1~500) |
| total_pages | number | 总页数 |
| evidences | array | 当前页证据列表,按 probability 降序 |
| evidences[].pmid | string | 证据 ID(引用时请逐字复制,禁止编造) |
| evidences[].probability | number | 该证据支持此关系的最高句级概率(0~1) |
| evidences[].pub_date | string | 文献发表日期(YYYY-MM-DD) |
| platform_credits_consumed | number | 本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1) |
| platform_credits_remaining | number | 本次调用后账户剩余积分(套餐额度 + 按量额度) |
说明:本接口返回路径中某一跳的证据(非全路径聚合),relID 来自 /details-indirect 的 relationships[]。人工注释跳的 evidences 恒为 [],仅收基础费。
错误码
| HTTP 状态 | 说明 | 是否计费 |
|---|
| 200 | 成功 | 按端点计费 |
| 400 | 参数缺失 / 格式错误,或计费失败 | 不计费 |
| 401 | API Key 缺失、无效或已禁用 | 不计费 |
| 402 | 配额不足(账户余额为 0) | 不计费 |
| 426 | Skill 版本过低需升级(仅 Skill 接入场景) | 不计费 |
| 4xx / 5xx | 上游服务错误(平台记录 consumption=0 的失败日志) | 不计费 |
承诺:所有失败请求(4xx / 5xx)完全不扣费。只有成功返回结果的请求才消耗 credits,请放心调试。
计费说明
API 调用按端点消耗 credits。详细计费规则请查看 计费规则页。以下是核心规则:
- 失败不计费:所有 4xx / 5xx 错误请求不消耗 credits
- 5 分钟缓存:相同参数 5 分钟内重复请求,命中缓存仅扣 1 credit
- 结果复用:result_id 永久有效,通过 result_id 获取详情比重新搜索更省
- 统一计费:API / Skill / MCP 三种方式共用同一套 credits,统一账单