API 文档

REST API · 8 个标准化端点 · Bearer Token 鉴权 · 按量计费 · 失败不收费

快速开始

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-indirect — 间接路径搜索(多跳)

POST/api/medgraph/search-indirect消耗 11 credits

搜索两实体之间经中间节点的间接路径(X → 中间体 → Y),适合机制链、药物重定位、靶点通路等问题。实体类型仅支持 Chemical / Disease / Gene。异步接口,流程同 /search。

请求参数

字段类型必填说明
entity_one_typestring是仅支持 Chemical / Disease / Gene
entity_one_namestring是实体一名称
entity_two_typestring否同上三类,缺省 Gene
entity_two_namestring是实体二名称
intermediate_nodesnumber否中间节点数上限,默认 1,最大 2(更深层成本陡增)
noveltystring否'1' 仅新颖路径,'0' 仅非新颖(过滤会剔除含人工注释跳的路径)
starting_date / ending_datestring否证据发表日期区间 YYYY-MM-DD(注意本端点字段名带 -ing)
directionstring否'12' 或 '21'(本端点仅支持这两个值)
enforce_refetchstring否"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
}

响应参数

字段类型说明
statusstring请求受理结果:成功排队固定返回 "success"
messagestring排队提示:任务已创建,需用 task_id 轮询 /status
task_idstring异步任务 ID,48 小时内有效;轮询 /status 至 completed 后换取 result_id
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:中间节点越多计算量越大(成本陡增),建议从 intermediate_nodes = 1 开始。缓存规则同 /search:5 分钟内相同请求体仅扣 1 credit。

POST /api/medgraph/resolve — 实体解析

POST/api/medgraph/resolve消耗 11 credits

校验实体是否存在于知识图谱,返回标准 entity_id 与已知别名。搜索结果为空时先用本接口排查实体名拼写,再用别名重试。

请求参数

字段类型必填说明
entity_typestring是实体类型:Gene, Chemical, Disease, Species, Anatomy, Biological Process, CellLine, Cellular Component, DNAMutation, Molecular Function, Pathway, Pharmacologic Class
entity_namestring是实体名称
entity_speciesstring否物种上下文,如 human、mouse(影响基因解析)
is_drugstring否"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
}

响应参数

字段类型说明
statusstring"success" 表示实体在图谱中命中
entity_idstring图谱标准实体 ID(biokdeid),搜索接口内部即按此 ID 定位节点
entity_typestring回显:实体类型
entity_namestring回显:实体名称
entity_speciesstring回显:物种上下文
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:未命中返回 HTTP 404 {"error": "Entity not found: ..."},不计费。名称按 officialName → commonName → 大小写不敏感 officialName 级联匹配;搜索无结果时可先用本接口排查拼写。

POST /api/medgraph/status — 任务状态查询

POST/api/medgraph/status消耗 1 credits

轮询异步搜索任务的状态。status 为 completed 后从响应取 result_id,调 /details 或 /details-indirect 获取结果。

请求参数

字段类型必填说明
task_idstring是搜索接口返回的任务 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
}

响应参数

字段类型说明
statusstring任务状态:pending 排队中 / running 执行中 / completed 已完成 / failed 失败
task_idstring回显:任务 ID
search_typestring任务类型:direct 直接搜索 / indirect 间接搜索
created_atstring任务提交时间(ISO 8601)
result_idstring仅 completed 返回:结果 ID,永久有效,用于 /details、/details-indirect 与证据接口
relations_countnumber仅 direct 任务完成时返回:关系总条数
paths_countnumber仅 indirect 任务完成时返回:路径总条数
errorstring仅 failed 返回:失败原因
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:task_id 48 小时后过期(轮询返回 404);result_id 永久有效,拿到后请立即保存。同一 task_id 轮询间隔需 ≥1 秒(建议 ≥3 秒),过密返回 429 且不计费。

POST /api/medgraph/details — 直接关系结果详情

POST/api/medgraph/details消耗 1 + 条目数 credits

获取已完成直接搜索任务的关系列表(含概率分)。每条关系带 relID,可调 /evidences 获取文献证据。

请求参数

字段类型必填说明
result_idstring是任务完成后返回的结果 ID
requested_relations_countnumber否拉取关系条数,默认 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_countnumber该结果的关系总条数
returned_countnumber本次实际返回条数(受 requested_relations_count 限制)
relationsarray关系列表,按 probability 降序;疾病亚型展开时按亚型分组(含 disease_name 字段)
relations[].relIDstring关系唯一标识(编码实体 ID、关系类型、方向、来源),调 /evidences 时原样传入
relations[].probabilitystring关系概率分(0~1),越高越可信
relations[].relation_detailsobject关系元数据(嵌套字段见下)
relation_details.node1Id / node1Name / node1Typestring实体一的图谱 ID / 显示名 / 类型
relation_details.node2Id / node2Name / node2Typestring实体二的图谱 ID / 显示名 / 类型
relation_details.scorenumber关系置信分
relation_details.relationship_typestring关系类型,如 Positive_Correlation、Association、treats
relation_details.correlation_typestring相关性:"2" 正相关 / "0" 负相关 / "1" 极性未知
relation_details.directionstring方向:"12" 实体一→实体二 / "21" 反向 / "0"、"NA" 无方向
relations[].evidence_countnumber该关系的文献证据条数;0 表示人工注释关系(无文献证据)
relations[].relation_seq_idnumber结果内序号
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:计费说明:消耗 = 1(基础费)+ 返回关系条目数。result_id 永久有效,重复查看同一结果建议复用 result_id 而非重新搜索。

POST /api/medgraph/details-indirect — 间接路径结果详情

POST/api/medgraph/details-indirect消耗 1 + 跳数之和 credits

获取已完成间接搜索任务的路径列表(X → 中间体 → Y)。每跳关系带 relID,可调 /evidences-indirect 获取证据。

请求参数

字段类型必填说明
result_idstring是任务完成后返回的结果 ID
requested_paths_countnumber否拉取路径条数,默认 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_countnumber该结果的路径总条数
returned_countnumber本次实际返回路径数(受 requested_paths_count 限制)
pathsarray路径列表,按 net_prob(净概率)降序
paths[].path_lengthnumber路径跳数(节点数 - 1)
paths[].net_correlationTypestring全路径净相关性:Positive_Correlation / Negative_Correlation
paths[].net_probnumber路径净概率(各跳概率连乘),越高越可信
paths[].nodesarray有序节点列表(起点 → 中间节点 → 终点)
nodes[].entity_idstring节点的图谱标准 ID
nodes[].namestring显示名(officialName 或 commonName)
nodes[].officialName / commonNamestring官方名 / 通用名
nodes[].typestring实体类型(Gene / Disease / Chemical)
paths[].relationshipsarray路径上的关系列表,每跳一个
relationships[].relIDstring该跳关系 ID,调 /evidences-indirect 取文献证据时传入
relationships[].relationshipTypestring关系类型,如 Association
relationships[].correlationTypestring相关性:Positive_Correlation / Negative_Correlation
relationships[].directionstring方向:"12" / "21" / "NA" / "0"
relationships[].scorenumber关系置信分
relationships[].probnumber该跳关系概率(0~1)
relationships[].evidence_countnumber该跳的文献证据条数;0 表示人工注释(无证据)
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:计费说明:消耗 = 1(基础费)+ 返回路径的总跳数(一条 2 跳路径计 2 条关系)。每跳 relID 可独立调 /evidences-indirect 取证据。

POST /api/medgraph/evidences — 直接关系证据

POST/api/medgraph/evidences消耗 1 + 证据条数 × 10 credits

获取某条直接关系的文献证据。relID 来自 /details 的返回。引用证据 ID 时请逐字复制,禁止编造。

请求参数

字段类型必填说明
result_idstring是结果 ID
relIDstring是关系 ID(来自 /details 返回)
pagenumber否页码,默认 1
page_sizenumber否每页条数,默认 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
}

响应参数

字段类型说明
statusstring"success" 表示查询成功
result_idstring回显:结果 ID
relIDstring回显:关系 ID
total_countnumber该关系的文献证据总条数(按证据去重);人工注释关系恒为 0
pagenumber当前页码(从 1 开始)
page_sizenumber每页条数(1~500)
total_pagesnumber总页数
evidencesarray当前页证据列表,按 probability 降序
evidences[].pmidstring证据 ID(引用时请逐字复制,禁止编造)
evidences[].probabilitynumber该证据支持此关系的最高句级概率(0~1)
evidences[].pub_datestring文献发表日期(YYYY-MM-DD)
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:人工注释(curated)关系没有文献抽取证据,evidences 恒为 [] 且仅收基础费。证据按最高句级概率排序,同一证据只出现一次。

POST /api/medgraph/evidences-indirect — 间接路径证据

POST/api/medgraph/evidences-indirect消耗 1 + 证据条数 × 10 credits

获取间接路径中某跳关系的文献证据。relID 来自 /details-indirect 的返回。

请求参数

字段类型必填说明
result_idstring是结果 ID
relIDstring是关系 ID(来自 /details-indirect 返回)
pagenumber否页码,默认 1
page_sizenumber否每页条数,默认 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
}

响应参数

字段类型说明
statusstring"success" 表示查询成功
result_idstring回显:结果 ID
relIDstring回显:关系 ID
total_countnumber该关系的文献证据总条数(按证据去重);人工注释关系恒为 0
pagenumber当前页码(从 1 开始)
page_sizenumber每页条数(1~500)
total_pagesnumber总页数
evidencesarray当前页证据列表,按 probability 降序
evidences[].pmidstring证据 ID(引用时请逐字复制,禁止编造)
evidences[].probabilitynumber该证据支持此关系的最高句级概率(0~1)
evidences[].pub_datestring文献发表日期(YYYY-MM-DD)
platform_credits_consumednumber本次调用消耗的平台积分(命中 5 分钟缓存时仅扣 1)
platform_credits_remainingnumber本次调用后账户剩余积分(套餐额度 + 按量额度)
说明:本接口返回路径中某一跳的证据(非全路径聚合),relID 来自 /details-indirect 的 relationships[]。人工注释跳的 evidences 恒为 [],仅收基础费。

错误码

HTTP 状态说明是否计费
200成功按端点计费
400参数缺失 / 格式错误,或计费失败不计费
401API Key 缺失、无效或已禁用不计费
402配额不足(账户余额为 0)不计费
426Skill 版本过低需升级(仅 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,统一账单