快速开始

1. 创建 API Key

API Key 可通过已认证的 Web 控制台管理。新创建的 Key 格式如下：

tk_0123456789abcdef0123456789abcdef

该 API Key 可在 Web 控制台中再次查看和复制。

2. 验证 Key 是否有效

请求任务列表来测试认证是否成功：

curl https://api.topmaterial-tech.com/api/v2/task/list \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

成功后会返回你的任务列表，说明 Key 可正常用于任务接口。

3. 创建一个任务

创建任务前，建议先用数据库接口发现可用的数据库：调用 GET /api/v2/database/by-task?task_type=line_calculation 筛选支持目标任务类型的数据库，并将返回的数据库 code 填入 task_config.tdb_code。创建任务会校验你对该数据库的订阅访问权限。

使用 JSON 请求体提交计算任务：

curl -X POST https://api.topmaterial-tech.com/api/v2/task \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Line-Calculation-Demo",
    "engine": "topthermo_next",
    "task_config": {
      "task_type": "line_calculation",
      "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
      "task_path": "",
      "condition": {
        "components": ["HF", "C"],
        "compositions_start": { "HF": 0.8, "C": 0.2 },
        "compositions_end": { "HF": 0.8, "C": 0.2 },
        "temperature_start": 300,
        "temperature_end": 3000,
        "pressure": 101325,
        "points": 101,
        "activated_phases": [],
        "topthermo_outputs": ["T", "P", "phase_name", "x(*)", "G", "H", "S"]
      }
    },
    "omp_threads": 4,
    "no_cache": false
  }'

engine 可省略，默认值为 topthermo_next。

响应会返回任务 ID 和初始状态：

响应中的 task_type 是服务端存储的具体计算类型，取自 task_config.task_type，因此本例返回 line_calculation。

{
  "id": 42,
  "status": "pending",
  "task_type": "line_calculation",
  "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB"
}

4. 轮询任务完成状态

不断查询任务状态直到完成：

curl https://api.topmaterial-tech.com/api/v2/task/42 \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

5. 获取结果文件

当任务状态变为 completed 后，获取结果文件列表：

curl https://api.topmaterial-tech.com/api/v2/task/42/result \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

下一步

阅读完整的认证指南。
使用数据库接口发现并筛选数据库。
查看所有任务操作接口。