任务接口（API Key）

以下接口允许你通过 API Key 认证来创建和管理 TopMat 任务。所有请求都必须在 Authorization 头中携带有效的 API Key。

任务概述

TopMat 任务是基于热力学数据库（TOPDB）和相场模型对材料体系进行数值计算的作业。典型的任务包括单点平衡计算、相图绘制、凝固模拟等。通过 API，你可以提交任务、查询进度、获取结果文件，并嵌入到自己的材料研发流程中。

工作流程

1. 发现并选择数据库：调用 GET /api/v2/database 浏览数据库，或用 GET /api/v2/database/by-task 按任务类型筛选，并用 POST /api/v2/database/{db_id}/phases 查询可用相，详见数据库接口。
2. 提交任务：调用 POST /api/v2/task，在 task_config 中传入具体计算类型（task_type）和数据库代码（tdb_code，即所选数据库的 code）。
3. 等待并执行：任务依次进入 pending → queued → running 状态。
4. 查询进度：使用 GET /api/v2/task/{id} 轮询任务状态，直到进入终态（completed / failed / aborted）。
5. 获取结果：任务完成后，调用 GET /api/v2/task/{id}/result 获取结果文件列表，或 GET /api/v2/task/{id}/preview、GET /api/v2/task/{id}/vtk 获取预览和 VTK 数据。

热力学计算（已上线）

任务类型	task_type	说明
单点平衡计算	point_calculation	在指定温度、压力和成分下计算体系的平衡相组成。
线计算	line_calculation	沿单一变量（如温度或成分）扫描，获取相变和相分数变化。
二元相图计算	binary_equilibrium	计算二元体系在温度-成分空间的相图。
热力学性质计算	thermodynamic_properties_next	输出定压热容、焓、熵、化学势等热力学函数。
Scheil 凝固模拟	scheil_solidification	基于 Scheil-Gulliver 模型模拟非平衡凝固路径。
三维相图计算	binary_cpt_diagram	在成分、温度、压力等条件空间中计算并展示相平衡关系。

警告

创建任务时，task_type 必须使用上表列出的六种取值之一。数据库接口返回的 support_task_list 中可能包含上表之外的历史兼容值，这些值不应用于创建任务。

相场模拟（开发中）

以下任务类型尚未开放，敬请期待：

• physical_vapor_deposition — 物理气相沉积
• cutting_process — 切削加工
• spinodal_decomposition — 调幅分解
• solidification — 凝固
• solution_treatment — 固溶处理
• aging — 时效处理
• directional_solidification — 定向凝固

通用 task_config 结构

不同任务类型的 task_config 字段略有差异，但通常包含以下共同字段：

task_config 通用结构示例

{
  "task_type": "point_calculation",
  "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
  "task_path": "examples/framework_demo/result/point_calculation_1",
  "condition": {
    "components": ["HF", "C"],
    "activated_phases": ["LIQUID", "HCP_A3_HF"],
    "temperature": 300,
    "compositions": { "HF": 0.7, "C": 0.3 }
  }
}

字段	类型	说明
task_type	string	具体计算类型，例如 line_calculation。它与外层 engine 字段职责不同：engine 选择执行器（热力学任务为 topthermo_next），task_type 选择该执行器内的计算类型。
tdb_code	string	热力学数据库代码，例如 TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB。
task_path	string	结果输出路径。
condition	object	计算条件，包含成分、温度、压力、激活相、输出项等。

注意

task_config 中的 task_name 字段会被服务端在入库前移除，无需填写；它不参与计算，也不影响缓存指纹。

关于 tdb_code

创建任务接口通过 tdb_code 指定数据库。服务端会根据 tdb_code 查找已启用的数据库记录，校验当前用户的订阅访问权限，然后把配置中的 tdb_code 替换为服务端管理的数据库文件路径（tdb_file）后再交给计算核心。tdb_code 的值是数据库的 code，可通过数据库接口发现和筛选。

为兼容旧客户端，缺少 tdb_code 时服务端会从 tdb_file 路径的文件名推导出数据库代码，客户端传入的文件路径本身不会被使用。

警告

创建任务接口会校验当前用户是否订阅了 tdb_code 对应的数据库；没有有效订阅时返回 403 Forbidden。创建前请先用数据库接口确认数据库存在、已激活且支持目标任务类型。

Base URL

Base URL

https://api.topmaterial-tech.com/api/v2

认证方式

使用 API Key 认证

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

创建任务

创建任务接口

POST /task

为 API Key 所属用户创建一个新任务。

请求体

请求体示例：线计算任务

{
  "title": "Line-Calculation-53",
  "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
}

字段	类型	必填	说明
title	string	是	任务标题。
engine	string	否	TaskMan 执行器。本文档列出的热力学计算使用 topthermo_next（默认值，可省略）；具体计算类型由 task_config.task_type 指定。
task_config	object	是	任务配置对象，必须为有效的 JSON 对象，且必须包含 task_type 和 tdb_code。
omp_threads	integer	否	OpenMP 线程数。
no_cache	boolean	否	为 true 时跳过计算缓存，默认 false。

注意

旧版兼容：未提供 task_config 时，服务端会尝试把外层 description 字段按 JSON 字符串解析为任务配置（旧客户端行为），新接入方请直接使用 task_config。

注意

缓存命中：未开启 no_cache 且已存在相同参数的已完成任务时，接口不会重复计算，而是直接返回 201 Created 且 status 为 completed。缓存指纹由 engine、tdb_code、omp_threads 和 task_config（不含 task_name、tdb_file、task_path 等与计算结果无关的字段）以及计算核心、数据库文件的版本指纹共同决定。

请求示例

创建线计算任务

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-53",
    "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
  }'

响应 — 201 Created

响应示例：任务创建成功

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

字段	类型	说明
id	integer	新建任务的 ID。
status	string	任务初始状态，通常为 pending；缓存命中时为 completed。
task_type	string	服务端存储的具体计算类型，取自 task_config.task_type；本例为 line_calculation。
tdb_code	string | null	任务使用的数据库代码。

校验错误 — 400 Bad Request

场景	消息
未提供 task_config（且无法从 description 解析）	task_config or description is required
task_config 不是 JSON 对象	task_config must be a JSON object
缺少 task_config.task_type	task_config.task_type is required
缺少 tdb_code（且无法从 tdb_file 推导）	task_config.tdb_code or task_config.tdb_file is required
tdb_code 不存在或未启用	TopDB code '<code>' was not found or is disabled
不支持的 engine	task type '<engine>' is not supported, ...

订阅校验 — 403 Forbidden

创建任务会校验当前用户对 tdb_code 对应数据库的订阅访问权限，无有效订阅时返回：

响应示例：无数据库访问权限

{
  "error": "the current subscription does not allow access to TopDB code 'TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB'"
}

限制

创建任务时会依次检查两类限制：

1. 创建任务次数限制：按当前角色订阅套餐的 task_using_limit 执行，统计窗口为滚动 24 小时。具体额度取决于用户当前生效的套餐。
2. 待处理任务数量限制：限制同一用户同时处于 pending 状态的任务数，具体上限由服务端部署配置决定。

超过待处理任务数量限制时，API 返回 403 Forbidden，并附带当前数量和本次生效的上限。以下示例假设部署上限为 200：

响应示例：超出待处理任务上限

{
  "error": "Pending task limit exceeded. Maximum allowed pending tasks: 200",
  "current_pending_tasks": 200,
  "max_pending_tasks": 200
}

超过套餐的 24 小时创建任务次数限制时同样返回 403 Forbidden。响应中的 used 和 limit 是当前用户的实际用量与套餐额度，例如：

响应示例：超出创建频率限制

{
  "error": "Rate limit exceeded: used 100 of 100 requests in the last 24 hours"
}

列出任务

列出任务接口

GET /task/list

以分页形式返回 API Key 用户拥有的任务列表。分页参数通过查询字符串（query）传递，不支持按状态或类型过滤。

查询参数

参数	类型	必填	说明
page	integer	否	页码，默认 1，最小 1。
items_per_page	integer	否	每页条数，默认 10，范围 1–100。
sort_order	string	否	asc（默认）或 desc，按任务 ID 排序。

请求示例

查询任务列表

curl "https://api.topmaterial-tech.com/api/v2/task/list?page=1&items_per_page=10&sort_order=asc" \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

响应示例：任务列表

{
  "data": [
    {
      "id": 42,
      "title": "Line-Calculation-53",
      "description": "{...}",
      "status": "completed",
      "task_type": "line_calculation",
      "result": "Task completed successfully",
      "logs": null,
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
      "created_at": "2026-05-20 08:00:00 UTC",
      "updated_at": "2026-05-20 08:05:00 UTC"
    }
  ],
  "total": 1,
  "total_pages": 1,
  "page": 1,
  "items_per_page": 10
}

字段	类型	说明
data	array	任务列表，每项为 TaskStatusResponse 对象。
data[].id	integer	任务 ID。
data[].title	string	任务标题。
data[].description	string	任务描述，为存储的 task_config 的 JSON 字符串。
data[].status	string	任务状态。
data[].task_type	string	任务类型。
data[].result	string | null	任务结果摘要。
data[].logs	string | null	任务日志。
data[].user_id	string	所属用户 UUID。
data[].tdb_code	string | null	任务使用的数据库代码。
data[].created_at	string	创建时间（UTC 字符串，形如 2026-05-20 08:00:00 UTC）。
data[].updated_at	string	更新时间（UTC 字符串）。
total	integer	总记录数。
total_pages	integer	总页数。
page	integer	当前页码。
items_per_page	integer	每页条数。

查看任务

查看任务接口

GET /task/{id}

按 ID 获取单个任务详情。该任务必须属于 API Key 用户。

路径参数

参数	类型	说明
id	integer	任务的数据库 ID（仅接受整数）。

请求示例

查询任务详情

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

响应 — 200 OK

响应示例：任务详情

{
  "id": 42,
  "title": "Line-Calculation-53",
  "description": "{...}",
  "status": "completed",
  "task_type": "line_calculation",
  "result": "Task completed successfully",
  "logs": null,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
  "created_at": "2026-05-20 08:00:00 UTC",
  "updated_at": "2026-05-20 08:05:00 UTC"
}

字段	类型	说明
id	integer	任务 ID。
title	string	任务标题。
description	string	任务描述，为存储的 task_config 的 JSON 字符串。
status	string	任务状态。
task_type	string	任务类型。
result	string | null	任务结果摘要。
logs	string | null	任务日志。
user_id	string	所属用户 UUID。
tdb_code	string | null	任务使用的数据库代码。
created_at	string	创建时间（UTC 字符串，形如 2026-05-20 08:00:00 UTC）。
updated_at	string	更新时间（UTC 字符串）。

错误

状态码	含义	响应体
403	无权访问该任务	{"error": "Access denied"}
404	任务不存在	{"error": "Task not found"}

取消任务

取消任务接口

PATCH /task/{id}/cancel

取消一个任务，将其状态设置为 aborted。只有处于 pending、queued 或 running 状态的任务才能取消。

路径参数

参数	类型	说明
id	integer	任务的数据库 ID（仅接受整数）。

请求示例

取消任务

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

响应 — 200 OK

响应示例：任务已取消

{
  "id": 42,
  "title": "Line-Calculation-53",
  "description": "{...}",
  "status": "aborted",
  "task_type": "line_calculation",
  "result": null,
  "logs": null,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tdb_code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
  "created_at": "2026-05-20 08:00:00 UTC",
  "updated_at": "2026-05-20 08:05:00 UTC"
}

字段	类型	说明
id	integer	任务 ID。
title	string	任务标题。
description	string	任务描述，为存储的 task_config 的 JSON 字符串。
status	string	取消后的任务状态，为 aborted。
task_type	string	任务类型。
result	string | null	任务结果摘要。
logs	string | null	任务日志。
user_id	string	所属用户 UUID。
tdb_code	string | null	任务使用的数据库代码。
created_at	string	创建时间（UTC 字符串）。
updated_at	string	更新时间（UTC 字符串）。

错误

状态码	含义	响应体
409	当前状态无法取消任务	{"error": "Task cannot be stopped in current status: completed"}

删除任务

删除任务接口

DELETE /task/{id}

永久删除一个任务。路径参数 {id} 接受整数数据库 ID 或任务 UUID。

如果任务仍处于可停止状态（pending、queued、running），系统会先停止它，然后再删除。

请求示例

删除任务

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

响应 — 204 No Content

删除成功时无响应体。

错误

状态码	含义	响应体
400	id 既不是整数也不是 UUID	{"error": "id must be an integer or uuid"}
404	任务不存在	{"error": "Task not found"}

获取结果文件

获取结果文件接口

GET /task/{id}/result

返回已完成任务的结果文件列表。

请求示例

获取结果文件

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

响应 — 200 OK

响应示例：结果文件列表

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    "https://storage.example.com/results/42/file1.dat?signature=..."
  ],
  "total_count": 1
}

字段	类型	说明
task_id	string	任务 UUID。
files	string[]	结果文件下载 URL 列表（预签名临时 URL）。
total_count	integer	文件总数。

获取预览文件

获取预览文件接口

GET /task/{id}/preview

返回任务的预览文件列表。

请求示例

获取预览文件

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

响应 — 200 OK

响应示例：预览文件列表

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    "https://storage.example.com/previews/42/preview.png?signature=..."
  ],
  "total_count": 1
}

字段	类型	说明
task_id	string	任务 UUID。
files	string[]	预览文件下载 URL 列表（预签名临时 URL）。
total_count	integer	文件总数。

获取 VTK 压缩包

获取 VTK 压缩包接口

GET /task/{id}/vtk

返回任务的 VTK 压缩文件信息。

请求示例

获取 VTK 压缩包

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

响应 — 200 OK

响应示例：VTK 文件列表

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    "https://storage.example.com/vtks/42/results.zip?signature=..."
  ],
  "total_count": 1
}

字段	类型	说明
task_id	string	任务 UUID。
files	string[]	VTK 压缩文件下载 URL 列表（预签名临时 URL）。
total_count	integer	文件总数。

任务状态

完整状态枚举如下。终态为 completed、failed、aborted；pending、queued、running 状态的任务可以取消。

状态	说明
created	任务已创建，尚未进入调度。
pending	任务等待被接收（可取消）。
queued	任务正在等待执行（可取消）。
running	任务正在执行（可取消）。
uploading	任务结果上传中。
completed	任务成功完成（终态）。
failed	任务执行失败（终态）。
aborted	任务被用户取消（终态）。

状态流转关系：

• created → queued / aborted / failed
• pending → queued / running / aborted / failed
• queued → running / uploading / aborted / failed
• running → uploading / aborted / failed
• uploading → completed / aborted / failed