API v1.0 — 生产环境

基于马属生物智能构建

编程访问最全面的马属生物学知识图谱。 查询品种、变异、表型和基础智能——所有结果均基于可溯源证据。

14
API 端点
17
品种
500K+
变异
100%
可溯源

5 分钟快速开始

从零到首次 API 调用,五分钟即可完成。无需信用卡。

1

创建开发者账号

eqaios.com/developers 注册并验证邮箱地址。

2

创建项目

在开发者控制台中创建新项目。每个项目拥有独立的 API Key 和用量配额。

3

生成 API Key

前往设置 → API Keys生成密钥。请妥善保管——密钥仅显示一次。

4

发起首次调用

查询品种端点以验证配置是否正常。

curl -X GET "https://api.eqaios.com/api/v1/breeds" \
  -H "Authorization: Bearer eqai_sk_your_api_key_here"
import requests

response = requests.get(
    "https://api.eqaios.com/api/v1/breeds",
    headers={"Authorization": "Bearer eqai_sk_your_api_key_here"}
)
print(response.json())
const response = await fetch('https://api.eqaios.com/api/v1/breeds', {
  headers: { 'Authorization': 'Bearer eqai_sk_your_api_key_here' }
});
const data = await response.json();
console.log(data);

Bearer Token 认证

所有 API 请求需通过 Authorization 请求头传递 API Key,使用 Bearer 方案。

🔑 认证请求头

在每个请求中包含你的 API Key:

Authorization: Bearer <YOUR_API_KEY>

🔄 OAuth 2.0(服务间认证)

对于自动化集成,使用客户端凭证流获取短期访问令牌:

{
  "grant_type": "client_credentials",
  "client_id": "eqai_client_abc123",
  "client_secret": "sk_live_...",
  "scope": "read:breeds read:variants read:knowledge"
}
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:breeds read:variants read:knowledge"
}

可用权限范围

read:breeds品种数据与变异
read:variants变异与证据
read:knowledge知识图谱
read:foundationFI 与 HorseVector
write:decision决策产品

公平使用与速率限制

每个 API 层级均包含充足的限额。速率限制响应头随每次响应返回。

层级 请求/分钟 突发 月度配额
免费 60 10 10,000
科研 300 50 100,000
商业 1,000 200 1,000,000
企业 定制 定制 无限
速率限制响应头: X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset

14 个核心端点

RESTful API 分为四个层级:数据访问层、知识图谱层、基础智能层和决策产品层。

数据访问层

GET
GET /api/v1/breeds 列出所有已基因分型的品种
GET /api/v1/breeds/{breed_id} 品种详情 + 表型
GET /api/v1/breeds/{breed_id}/variants 品种特异性变异频率
GET /api/v1/variants/{rsID} 变异详情 + 完整证据
GET /api/v1/variants/{rsID}/evidence 变异完整证据链
GET /api/v1/variants/{rsID}/validation 验证状态与历史

知识图谱层

GET
GET /api/v1/knowledge/search 跨所有实体语义搜索
GET /api/v1/knowledge/graph/{gene_id} 基因完整子图
GET /api/v1/knowledge/phenotypes/{id} 表型与关联实体

基础智能层

GET / POST
GET /api/v1/foundation/{entity_id} 实体基础智能
POST /api/v1/foundation/embed 生成 HorseVector 嵌入

决策产品与搜索

POST / GET
POST /api/v1/jumphealth/screen 遗传疾病风险筛查
POST /api/v1/jumpid/identify 基因身份鉴定
POST /api/v1/jumpchain/verify 血统验证
GET /api/v1/search 全数据统一搜索

核心 API 详情

构建马属生物智能应用最常用的四个端点。

GET /api/v1/breeds

品种查询

列出所有已基因分型的品种,包含基因分型数量、变异数量和生产状态。可按 status=productionintegrating 过滤。

status page per_page
GET /api/v1/variants/{rsID}

变异查询

完整变异详情,包括坐标、等位基因、品种特异性频率、表型和完整证据链及可溯源性。

rsID traceability_chain breed_frequencies
GET /api/v1/knowledge/graph/{gene_id}

知识图谱

检索基因的完整知识子图——关联的变异、表型和品种,包含边类型和验证状态。

depth edge_types knowledge_node knowledge_edge
POST /api/v1/foundation/embed

HorseVector 嵌入

为任何马属生物实体生成 1024 维 HorseVector 嵌入——基因、变异、品种或自定义基因分型数据。

entity_type entity_id 1024-dim model_version

标准响应格式

每个 API 响应遵循严格的信封格式,确保一致性、可溯源性和科学问责性。

data 必填
object
核心响应数据。结构因端点而异。
traceability 必填
object
从输出到来源的证据链——彻底的可溯源性。
confidence 必填
object { value, methodology }
统计置信度(0.0–1.0)及方法说明。
version 必填
object { data_version, data_timestamp }
数据来源——真相是有版本的。
validation_status 必填
string
顶层证据质量标签。
pagination
object
page, per_page, total, total_pages(仅列表端点)。
示例响应
{
  "data": {
    "breed_id": "TB",
    "name": "Thoroughbred",
    "status": "production",
    "genotype_count": 12450,
    "variant_count": 487230
  },
  "traceability": {
    "source_papers": ["PMID:34567890"],
    "coordinate_system": "EquCab3.0",
    "validation_status": "validated"
  },
  "confidence": {
    "value": 0.97,
    "methodology": "cross-breed validation with 8 independent populations"
  },
  "version": {
    "data_version": "2026.07.01",
    "data_timestamp": "2026-07-01T00:00:00Z"
  },
  "validation_status": "validated"
}

验证状态标签

每个响应包含验证状态,指示证据质量。这不是置信度评分——它反映的是独立验证结果。

✅ validated ⚠️ partially_validated 🔴 unvalidated 📋 under_review
已验证

经 ≥2 个独立来源确认。在 dbSNP + OMIA + 文献中交叉引用。

部分验证

部分证据存在,需进一步确认。等待独立复现。

未验证

初步阶段,仅为假说。尚未进行独立验证。

审核中

正由领域专家评估。已提交专家审核。

代码示例

最常见集成模式的真实示例。可在 cURL、Python 和 JavaScript 之间切换。

查询品种数据

# Get detailed info for the Thoroughbred breed
curl -X GET "https://api.eqaios.com/api/v1/breeds/TB" \
  -H "Authorization: Bearer eqai_sk_your_api_key"
import requests

API_KEY = "eqai_sk_your_api_key"
BASE = "https://api.eqaios.com/api/v1"

# Get detailed info for the Thoroughbred breed
resp = requests.get(
    f"{BASE}/breeds/TB",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
breed = resp.json()

print(f"Breed: {breed['data']['name']}")
print(f"Genotypes: {breed['data']['genotype_count']:,}")
print(f"Validation: {breed['validation_status']}")
print(f"Confidence: {breed['confidence']['value']}")
const API_KEY = 'eqai_sk_your_api_key';
const BASE = 'https://api.eqaios.com/api/v1';

// Get detailed info for the Thoroughbred breed
const resp = await fetch(`${BASE}/breeds/TB`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const breed = await resp.json();

console.log(`Breed: ${breed.data.name}`);
console.log(`Genotypes: ${breed.data.genotype_count.toLocaleString()}`);
console.log(`Validation: ${breed.validation_status}`);

知识图谱查询

# Get the knowledge subgraph for the MSTN gene
curl -X GET "https://api.eqaios.com/api/v1/knowledge/graph/MSTN?depth=2" \
  -H "Authorization: Bearer eqai_sk_your_api_key"
import requests

API_KEY = "eqai_sk_your_api_key"
BASE = "https://api.eqaios.com/api/v1"

# Get the knowledge subgraph for MSTN gene
resp = requests.get(
    f"{BASE}/knowledge/graph/MSTN",
    params={"depth": 2},
    headers={"Authorization": f"Bearer {API_KEY}"}
)
graph = resp.json()

focal = graph["data"]["focal_node"]["knowledge_node"]
print(f"Gene: {focal['name']} ({focal['id']})")

for node in graph["data"]["nodes"]:
    n = node["knowledge_node"]
    print(f"  → {n['node_type']}: {n.get('name', n['id'])}")

for edge in graph["data"]["edges"]:
    e = edge["knowledge_edge"]
    print(f"  {e['source']} —[{e['relation']}]→ {e['target']}")
const API_KEY = 'eqai_sk_your_api_key';
const BASE = 'https://api.eqaios.com/api/v1';

// Get the knowledge subgraph for MSTN gene
const resp = await fetch(
  `${BASE}/knowledge/graph/MSTN?depth=2`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const graph = await resp.json();

const focal = graph.data.focal_node.knowledge_node;
console.log(`Gene: ${focal.name} (${focal.id})`);

graph.data.nodes.forEach(node => {
  const n = node.knowledge_node;
  console.log(`  → ${n.node_type}: ${n.name || n.id}`);
});

graph.data.edges.forEach(edge => {
  const e = edge.knowledge_edge;
  console.log(`  ${e.source} —[${e.relation}]→ ${e.target}`);
});

生成 HorseVector 嵌入

# Generate a HorseVector for a variant
curl -X POST "https://api.eqaios.com/api/v1/foundation/embed" \
  -H "Authorization: Bearer eqai_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "variant",
    "entity_id": "rs112719330"
  }'
import requests

API_KEY = "eqai_sk_your_api_key"
BASE = "https://api.eqaios.com/api/v1"

# Generate HorseVector for the MSTN speed variant
resp = requests.post(
    f"{BASE}/foundation/embed",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "entity_type": "variant",
        "entity_id": "rs112719330"
    }
)
hv = resp.json()

print(f"Dimensions: {hv['data']['horsevector']['dimensions']}")
print(f"Model: {hv['data']['horsevector']['model_version']}")
print(f"Vector (first 5): {hv['data']['horsevector']['embedding'][:5]}")
const API_KEY = 'eqai_sk_your_api_key';
const BASE = 'https://api.eqaios.com/api/v1';

// Generate HorseVector for the MSTN speed variant
const resp = await fetch(`${BASE}/foundation/embed`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entity_type: 'variant',
    entity_id: 'rs112719330'
  })
});
const hv = await resp.json();

console.log(`Dimensions: ${hv.data.horsevector.dimensions}`);
console.log(`Model: ${hv.data.horsevector.model_version}`);
console.log(`Vector (first 5):`, hv.data.horsevector.embedding.slice(0, 5));

SDK 与库

官方 SDK 内置完整类型安全、自动分页和术语合规。

🐍

eqai-python

Python 3.9+ · Pydantic 类型

全功能 SDK,支持异步、流式响应和自动响应信封解析。

规划中
pip install eqai
📊

eqai-r

R 4.0+ · S4 类

原生 R 集成,内置知识图谱可视化和统计分析工具。

规划中
install.packages("eqai")

@eqai/sdk

TypeScript · Node 18+

TypeScript 优先的 SDK,完整类型定义、流式支持和可摇树模块。

规划中
npm install @eqai/sdk

EQAI CLI

命令行工具,用于快速查询、数据探索和管道集成。

Terminal
# Install the CLI
pip install eqai-cli

# Configure your API key
eqai auth login

# Query breed information
eqai breeds list --status production

# Get variant details
eqai variants get rs112719330 --format json

# Search the knowledge graph
eqai knowledge search "MSTN speed" --depth 2

# Generate a HorseVector
eqai embed --entity-type variant --entity-id rs112719330

# Run genetic disease screening
eqai jumphealth screen --breed TB --genotype genotype.vcf

开发者支持

获取帮助、分享反馈,与马属生物学开发者社区连接。

准备好构建了吗?

立即开始将马属生物智能集成到你的应用中。 提供免费层级——无需信用卡。

获取你的 API Key → 浏览 API 文档

生物学先于计算而存在。EQAI 的使命是让生物学可计算化。