结构预测使用指南 | 深旋科技文档中心

结构预测用于根据蛋白质、DNA、RNA、小分子配体或离子输入，预测单个分子体系的三维结构。多个分子实体可以放在同一任务中，作为一个复合物进行预测。

结构预测使用 Melo-1 模型，任务类型为 1。本指南说明如何准备输入、询价、提交与获取结果；接口字段和状态定义见任务管理 API，身份认证见 API 接入指南。如需将同一靶点与多个候选分别组合并比较，请参阅虚拟筛选使用指南。

使用流程

准备输入：在 input.sequences 中填写本次预测的分子实体与链标识。
查询费用：调用 POST /v1/tasks/quote，确认 Token 数与预估所需点数。
提交任务：使用相同的模型、任务类型和输入调用 POST /v1/tasks/create，保存返回的 task_id。
查询与下载：通过 GET /v1/tasks/status 查询状态，成功完成后使用 output_url 下载完整结果 ZIP。
查看结果：查看结构结果，或使用结构预测结果报告模板生成可离线打开的交互报告。

输入格式

以下示例将一条蛋白质链与一个小分子配体放在同一复合物中预测。将请求保存为 prediction.json，用于下方的询价与提交示例：

{
  "model": "Melo-1",
  "task_type": 1,
  "input": {
    "num_seeds": 1,
    "sequences": [
      {
        "type": "protein",
        "id": ["A"],
        "sequence": "MKTIIALSYIFCLVFADYKDDDDK"
      },
      {
        "type": "ligand",
        "id": ["B"],
        "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
      }
    ]
  }
}

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

请求参数

字段	类型	必填	描述
`model`	string	否	省略时为 `Melo-1`；目前仅开放该模型
`task_type`	int	否	结构预测使用 `1`，也是省略时的默认值
`task_name`	string	否	仅创建任务时使用，命名规则见提交推理任务
`input.sequences`	array	是	本次预测的分子实体列表，至少包含一项
`input.num_seeds`	int	否	推理随机种子数量，默认 `1`；取值为 `1`～`20`，费用按该数量倍增

结构预测的 input 使用 sequences，请勿混入虚拟筛选的 target 或 candidates。仅传入本文说明的输入参数。

推理种子数量

设置 input.num_seeds，可对同一分子体系使用多个随机种子进行预测。省略时使用 1；显式传入 0、负数或大于 20 的值会返回 INVALID_ARGUMENT。该参数必须是整数，仅结构预测支持，虚拟筛选不支持。

num_seeds 表示随机种子的数量，不用于指定某个种子的具体值，也不是最终结构文件的数量。目前每个 seed 生成 5 个结构样本，例如 num_seeds: 20 对应 100 个结构样本。增加种子数量可获得更多候选结构，但不保证预测质量提高。

结构预测费用为 Token 阶梯基础费用 × num_seeds，Token 数及 2,000 Token 上限不随种子数量倍增。例如 420 Token 的基础费用为 10 点，设置 num_seeds: 20 时为 200 点。

询价与提交时应使用相同的 input.num_seeds；修改数量后请重新询价，并相应调整顶层 max_cost。

模型与分子类型

模型	支持的 `type`
`Melo-1`	`protein`、`dna`、`rna`、`ligand`、`ion`

模型名和分子类型均区分大小写，请使用表中给出的写法。

`sequences` 元素

字段	类型	必填	描述
`type`	string	是	分子实体类型，且必须受所选模型支持
`id`	array[string]	是	链标识列表，必须包含 1～50 个互不重复的值；每个值长度为 1～50，只能包含字母、数字、下划线、点和连字符
`sequence`	string	条件必填	`protein`、`dna`、`rna` 必填；单条序列长度至少为 4；请求中的空白字符会被忽略
`smiles`	string	条件必填	`ligand` 或 `ion` 至少提供 `smiles`、`ccd` 之一；两者同时提供时使用 `smiles`
`ccd`	string	条件必填	PDB CCD 编码，建议使用大写，例如 `ATP`、`HEM`、`MG`

序列字符与长度要求：

单条序列长度：protein、dna、rna 的单条序列最短长度限制为 4（小于 4 将返回 INVALID_SEQUENCE 错误）。
可用字符：

类型	可用字符
`protein`	20 种标准氨基酸单字母：`ACDEFGHIKLMNPQRSTVWY`
`dna`	`ATCG`
`rna`	`AUCGN`

建议使用大写序列。平台还会验证 SMILES 和 CCD 是否有效。Token 计算方法见计价与配额规则。

询价与提交

查询费用

使用您的 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 @prediction.json

响应中的 data.token_num 是所有输入分子的 Token 总数，不乘以种子数量；data.base_cost 是该 Token 档位的单份基础费用，data.quantity 是实际采用的种子数量。data.estimated_cost 已包含数量对应的费用，无需再次相乘。具体阶梯见计价与配额规则。

询价不会创建任务或冻结点数，也不锁定价格。确认报价后，可使用同一份输入提交；实际预占点数以创建响应的 billing_order.frozen 为准。

提交并查询任务

以下两种调用方式任选其一。Python 示例需要已安装 requests，并从上方保存的 prediction.json 读取输入。

import json
from pathlib import Path

import requests

BASE_URL = "https://api.atomelody.com"
API_KEY = "ak_your_api_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = json.loads(Path("prediction.json").read_text(encoding="utf-8"))
payload["task_name"] = "Demo_Task"  # 可选，仅创建任务时提供

response = requests.post(
    f"{BASE_URL}/v1/tasks/create",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
result = response.json()
if result["code"] != "OK":
    raise RuntimeError(f'{result["code"]}: {result["message"]}')

task_id = result["data"]["task_id"]
print("任务 ID:", task_id)
print("预占点数:", result["data"]["billing_order"]["frozen"])

query = requests.get(
    f"{BASE_URL}/v1/tasks/status",
    headers=headers,
    params={"task_id": task_id},
    timeout=30,
)
query.raise_for_status()
print(query.json())

示例只查询一次状态，任务可能尚未结束。后续使用任务等待脚本等待同一个 task_id，无需重复创建任务。通用状态、取消条件和错误处理见任务管理 API。

查询状态与下载结果

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

任务状态	处理方式
`1`（`CREATED`）或 `2`（`QUEUED`）	等待任务开始；如需取消，可调用取消任务接口
`3`（`RUNNING`）	继续查询状态，等待计算完成
`4`（`COMPLETED`）	通过 `output_url` 下载完整结果 ZIP
`5`（`FAILED`）	查看 `data.error.code`；预占点数自动释放
`6`（`CANCELLED`）	任务已取消，预占点数自动释放

查询接口顶层的 code: "OK" 仅表示查询请求成功，计算是否完成取决于 data.status。下载地址有效期为 10 分钟，过期后重新查询任务即可获取新地址。

结果使用

建议将完整结果 ZIP 保存为 <任务 ID>-output.zip，保留任务 ID 以便关联输入与结果。

如需交互查看三维结构、切换候选结构并查看排名分数与置信度，可按生成结构预测结果报告操作，让 agent 将完整 ZIP 嵌入 HTML 模板，生成可离线打开的报告，也可从报告中导出结构文件。

报告包含预测结果数据，分享前请确认接收范围。报告无需填入 API Key 或临时下载地址。