虚拟筛选使用指南

虚拟筛选用于将同一靶点与多个候选分子分别组合，批量预测复合物结构，并汇总候选的排名与置信度。您可以通过一次任务比较多条候选肽或多个小分子配体，也可以为每个候选提供多个分子实体。

虚拟筛选使用 Melo-1 模型，任务类型为 2，沿用任务管理 API 的询价、创建、查询、列表与取消接口。身份认证和通用响应格式见 API 接入指南。

使用流程

1. 准备输入：填写共用靶点 target，为每个候选分配唯一的 id 并填写分子信息。
2. 查询费用：调用 POST /v1/tasks/quote，确认每个组合的 Token 数和整批预估费用。
3. 提交任务：使用相同的模型、任务类型和输入调用 POST /v1/tasks/create，保存返回的 task_id。
4. 查询与下载：通过 GET /v1/tasks/status 查询任务；任务结束后，使用 output_url 下载结果 ZIP。
5. 查看候选结果：先阅读 summary.csv，再根据候选 ID 查看对应的结构结果。

输入格式

以下示例将一条靶点蛋白分别与两条候选肽组合。候选肽使用 protein 类型；小分子候选则使用 ligand，并提供 smiles 或 ccd。

将以下请求保存为 screening.json，可直接用于下方的询价与提交示例：

{
  "model": "Melo-1",
  "task_type": 2,
  "input": {
    "target": {
      "sequences": [
        {
          "type": "protein",
          "id": ["A"],
          "sequence": "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
        }
      ]
    },
    "candidates": [
      {
        "id": "peptide1",
        "sequences": [
          { "type": "protein", "id": ["B"], "sequence": "ACDEFGHIKLMNPQRSTVWY" }
        ]
      },
      {
        "id": "peptide2",
        "sequences": [
          { "type": "protein", "id": ["B"], "sequence": "ACDEFGHIKL" }
        ]
      }
    ]
  }
}

示例用于说明请求格式，不代表经过验证的结合分子。

请求参数

分子实体参数

target.sequences 和各候选的 sequences 使用以下字段。模型名和分子类型均区分大小写。

建议使用大写序列。平台还会验证 SMILES 和 CCD 是否有效。仅传入本指南说明的输入参数。

候选与链标识

• 候选 ID：长度为 1～100，只能包含英文字母、数字、下划线和连字符，且必须以字母或数字开头。同一任务内忽略大小写后不可重复，例如 peptide1 与 Peptide1 不能同时使用。
• 链标识 sequences[].id：每项包含 1～50 个链标识，每个标识长度为 1～50；虚拟筛选的链标识只能包含英文字母和数字。
• 组合内唯一：靶点与任意一个候选组成的复合物中，链标识不可重复。不同候选之间可以复用链标识；例如上面的两个候选都使用 B，但不能与靶点共用 A。
• 序列格式：建议提供不含空白的大写序列。蛋白质、DNA 和 RNA 单条序列至少包含 4 个残基或碱基。

如需指定用于模板搜索的蛋白质序列，可在靶点的 protein 实体中提供可选字段 template_seq。该字段仅用于靶点蛋白，使用标准氨基酸单字母序列，最长为 2,000；省略、传入 null 或空字符串时使用默认模板搜索方式。实际预测的靶点序列仍由 sequence 指定。

询价与提交

查询整批与逐候选费用

使用您的 API Key 替换示例中的占位值：

curl --request POST 'https://api.atomelody.com/v1/tasks/quote' \
  --header 'Authorization: Bearer ak_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data-binary @screening.json

上面的输入包含 76 个残基的靶点，以及分别为 20 和 10 个残基的候选肽。响应示例：

{
  "code": "OK",
  "message": "OK",
  "data": {
    "token_num": 182,
    "base_cost": 20,
    "quantity": 1,
    "estimated_cost": 20,
    "candidate_costs": [
      { "candidate_id": "peptide1", "token_num": 96, "estimated_cost": 10 },
      { "candidate_id": "peptide2", "token_num": 86, "estimated_cost": 10 }
    ]
  }
}

2,000 Token 上限适用于每个组合，不适用于所有组合累加后的 token_num。费用按组合分别套用阶梯后求和，不将整批 Token 合并套用一次阶梯。详细规则见虚拟筛选计费。

询价不会创建任务或冻结点数，也不锁定价格。询价与创建均会校验 1,000 点的单任务费用上限；超出时返回 INVALID_ARGUMENT。分子输入或单个组合 Token 数不合法时返回 INVALID_SEQUENCE。

提交筛选任务

确认报价后，使用同一份输入提交：

如需限制本次任务的点数消耗，可在 screening.json 顶层添加 max_cost，值取询价返回的 data.estimated_cost（上例为 20）。创建时整批费用超过此值会返回 MAX_COST_EXCEEDED，不会创建任务或冻结点数；省略或设为 0 则不设置用户费用上限。1,000 点的单任务费用上限仍然生效。

curl --request POST 'https://api.atomelody.com/v1/tasks/create' \
  --header 'Authorization: Bearer ak_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data-binary @screening.json

创建成功后的字段定义见任务创建响应。保存 data.task_id，并通过 data.billing_order.frozen 确认本次实际预占的点数。

查询状态与下载结果

长时间等待时，推荐使用任务等待脚本，由脚本自动查询，只输出状态变化和最终结果。

curl --get 'https://api.atomelody.com/v1/tasks/status' \
  --header 'Authorization: Bearer ak_your_api_key_here' \
  --data-urlencode 'task_id=<TASK_ID>'

状态接口仅返回任务 ID、状态，以及按需返回的结果地址和错误；如需查看 task_type、靶点与候选输入，可调用 /v1/tasks/query 获取详情。状态编码与任务状态表一致；候选的执行结果需从下载包中的 summary.csv 查看。

output_url 有效期为 10 分钟，过期后重新查询任务即可获取新地址。下载时使用返回的完整 URL；任务错误处理和取消规则见任务管理 API。

结果文件与解读

结果 ZIP 的根目录包含一份汇总表和成功候选的结果 ZIP。例如两个候选均成功时：

output.zip
├── summary.csv
├── peptide1.zip
└── peptide2.zip

summary.csv 保留所有候选。失败候选没有对应的结构 ZIP；若全部候选失败且已生成汇总结果，下载包中仅包含 summary.csv。

汇总表常用字段

成功候选排在汇总表前部，失败候选排在后部。请按列名读取 CSV，并通过 id 关联输入与结果文件，不要依赖输入顺序或固定列位置；未列出的附加字段可以忽略。失败候选的评分为空，不应将空值当作零分参与比较。

建议结合排名分数、界面置信度、碰撞情况与具体结构共同评估候选。样本间评分差异反映分数变化，不能直接视为结构收敛程度；这些指标也不等同于实验测得的结合亲和力或活性。

可使用虚拟筛选结果报告模板，将整批 ZIP 生成为可离线打开的交互报告，在候选排名表中定位结果，再查看每个候选的三维结构、PAE 与 pLDDT。