通过 API 调用 Job 任务

共绩算力提供 Open API 接口，用户可通过 API 调用 job 任务，如启动任务、停止任务、查询任务状态、获取任务结果等，实现任务的自动化调度和管理。

一、前置准备

• 登录共绩算力个人中心后台，访问 API 密钥管理页面，点击“新建密钥”，选择模式并生成 (为降低密钥泄漏的风险，密钥创建后仅会展示一次，请及时保存。如果丢失，需要重新创建新的密钥。)
• 熟悉 API 接口文档：查看共绩算力Open API 文档，明确各接口的请求地址、请求方法、参数说明、返回格式等。

二、通用规范

• 请求头：所有 API 请求需携带身份验证信息，请求头格式如下：https://openapi.suanli.cn
• 请求方法：根据接口类型，使用 GET（查询）、POST（创建/启动/停止）方法。
• 请求参数：分为路径参数、查询参数、请求体参数，需严格按照接口文档要求传递，参数格式为 JSON。
• 返回结果：所有 API 返回结果均为 JSON 格式，包含状态码（code）、提示信息（message）、数据（data），其中 code=200 表示请求成功。

三、调用示例

查询 job 任务列表

参数解析：

• status：任务状态。如果有多个值，请使用英文逗号（,）分隔
• type：任务类型
• page：页码
• page_size：每页数量
• token：请填入您在平台内创建的 API 密钥，获取路径为：右上角头像 → API 密钥
• timestamp：时间戳（示例：1770194570564）
• version：固定值（示例：1.0.0）

获取设备资源列表

参数解析：

• task_type：任务类型
• device_type：设备类型

创建指定的 job 任务

body 参数参考文档

{
  "job_support": {
    "mod_param": {
      "default": {
        "backoff_limit": 3,
        "restart_policy": "OnFailure"
      }
    },
    "parallelism": 1,
    "timeout_sec": 86400,
    "estimated_exec_sec": 600
  },
  "task_name": "j01081829-dailyhot10",
  "points": 1,
  "resources": [
    {
      "resource": {
        "device_name": "4090-48G x 8",
        "region": "chengde-p1",
        "gpu_name": "4090-48G",
        "gpu_count": 8,
        "gpu_memory": 3145728,
        "memory": 516096,
        "cpu_cores": 128
      },
      "region_name": "先择所需区域",
      "mark": "通过查询资源来获取"
    }
  ],
  "services": [
    {
      "env": [],
      "health_checks": {
        "liveness_probe": {
          "failure_threshold": 3,
          "initial_delay_seconds": 0,
          "path": "/live",
          "period_seconds": 10,
          "port": 80,
          "probe_type": "httpGet",
          "switch": false,
          "timeout_seconds": 1
        },
        "readiness_probe": {
          "failure_threshold": 3,
          "initial_delay_seconds": 0,
          "path": "/ready",
          "period_seconds": 10,
          "port": 80,
          "probe_type": "httpGet",
          "switch": false,
          "timeout_seconds": 1
        },
        "startup_probe": {
          "failure_threshold": 3,
          "initial_delay_seconds": 0,
          "path": "/health",
          "period_seconds": 10,
          "port": 80,
          "probe_type": "httpGet",
          "switch": false,
          "timeout_seconds": 1
        }
      },
      "is_update_repository": null,
      "remote_ports": [],
      "repository_account": null,
      "resource_weight": {
        "cpu_weight": 1,
        "gpu_weight": 1,
        "mem_weight": 1
      },
      "service_image": "所需镜像地址",
      "service_name": "j1767868176690-5675100",
      "share_disk_config": [],
      "share_mem_config": [],
      "share_storage_config": [],
      "start_script": {
        "command": [
          "sleep"
        ],
        "args": [
          "300"
        ]
      },
      "storage_config": []
    }
  ],
  "share_disk_volumes": [],
  "share_mem_volumes": [],
  "task_qos": null,
  "task_type": "Job",
  "sub_type": "Spot"
}

参数注释解析

1 .顶层字段

字段	类型	必填	说明	示例/备注
job_support	Object	必填	任务运行配置	见下方 job_support 子表
task_name	String	必填	任务名称，需在平台唯一	"j01081829-dailyhot10"
points	Number	必填	任务对应的积分数，用于计费或优先级	1
resources	Array	必填	资源申请列表，通常只包含一个对象	见下方 resources 数组子表
services	Array	必填	容器服务配置列表，通常只包含一个对象	见下方 services 数组子表
share_disk_volumes	Array	可选	共享磁盘卷配置，无则空数组	[]
share_mem_volumes	Array	可选	共享内存卷配置，无则空数组	[]
task_qos	Null / String	可选	任务 QoS 级别，通常可为 null	null
task_type	String	必填	任务类型，固定为 Job	"Job"
sub_type	String	必填	子类型，例如 Spot 或 OnDemand	"Spot"

2 .job_support 字段

字段	类型	必填	说明	示例
mod_param	Object	必填	作业控制参数
mod_param.default	Object	必填	默认配置
mod_param.default.backoff_limit	Number	必填	失败重试次数上限	3
mod_param.default.restart_policy	String	必填	重启策略：OnFailure、Never、Always	"OnFailure"
parallelism	Number	必填	并行运行的 Pod 数量	1
timeout_sec	Number	必填	任务超时时间，单位为秒	86400，即 1 天
estimated_exec_sec	Number	可选	预估执行时间，单位为秒，用于调度优化	600，即 10 分钟

3 .resources 数组内的对象字段

字段	类型	必填	说明	示例/备注
resource	Object	必填	详细的资源规格，部分平台可能不需要嵌套，请查阅文档	见下表
region_name	String	必填	资源所在区域的中文名称	必须替换为真实区域名，如 "河北六区"
mark	String	必填	资源标识码，由平台分配，需要通过资源查询接口获取	占位符无效，必须替换为真实 mark 字符串

4 .resource 对象内部字段

字段	类型	说明	示例
device_name	String	设备名称	"4090-48G x 8"
region	String	区域代码	"chengde-p1"
gpu_name	String	GPU 型号	"4090-48G"
gpu_count	Number	GPU 数量	8
gpu_memory	Number	总显存，单位为 MB	3145728
memory	Number	系统内存，单位为 MB	516096
cpu_cores	Number	CPU 核心数	128

注意：部分平台可能不接受 resource 这种嵌套结构，请以官方文档为准。更常见的方式是直接在 resources 对象中平铺 gpu_name、gpu_count 等字段，或仅提供 mark 即可自动关联资源规格。

5 .services 数组内的对象字段

字段	类型	必填	说明	示例/备注
env	Array	可选	环境变量列表	每个元素格式为 {"name":"KEY","value":"VAL"}
health_checks	Object	可选	健康检查配置，若不需要可移除整个对象	见下方探针表格
is_update_repository	Null	可选	是否更新仓库，通常为 null	null
remote_ports	Array	可选	需要暴露的远程端口列表	[]
repository_account	Null	可选	私有镜像仓库账户，无则为 null	null
resource_weight	Object	视平台要求	资源权重，部分平台要求放在顶层	见下方说明
service_image	String	必填	容器镜像地址	必须替换为有效镜像，例如 "harbor.suanleme.cn/project/ubuntu:22.04"
service_name	String	必填	服务名称，建议保持唯一	"j1767868176690-5675100"
share_disk_config	Array	可选	共享磁盘挂载配置	[]
share_mem_config	Array	可选	共享内存挂载配置	[]
share_storage_config	Array	可选	共享存储挂载配置	[]
start_script	Object	必填	容器启动命令及参数	见下方 start_script 表
storage_config	Array	可选	存储卷挂载配置	[]

6 .health_checks 下的探针字段

适用于：

• liveness_probe
• readiness_probe
• startup_probe

每个探针的结构相同：

字段	类型	必填	说明	示例
failure_threshold	Number	必填	连续失败次数阈值	3
initial_delay_seconds	Number	必填	容器启动后延迟探测时间，单位为秒	0
path	String	probe_type 为 httpGet 时必填	"/live"
period_seconds	Number	必填	探测间隔，单位为秒	10
port	Number	HTTP 探测时必填	80
probe_type	String	必填	探测类型，支持 httpGet、tcpSocket、exec	"httpGet"
switch	Boolean	必填	是否启用该探针	false，表示禁用
timeout_seconds	Number	必填	探测超时时间，单位为秒	1

建议：如果 switch 为 false，表示探针被禁用，但某些 API 仍要求保留所有字段。若不需要任何探针，可尝试省略整个 health_checks 对象。

7 .resource_weight 对象

字段	类型	说明	示例
cpu_weight	Number	CPU 权重系数	1
gpu_weight	Number	GPU 权重系数	1
mem_weight	Number	内存权重系数	1

历史错误提示：之前出现过 “missing field ‘resource_weight’” 错误，可能是因为平台期望该字段在顶层，即与 task_name 同级，且类型为数字，例如 “resource_weight”: 1。请务必查阅官方文档确认正确的位置和类型。

8 .start_script 对象

字段	类型	说明	示例
command	Array	可执行命令，第一个元素为命令名	["sleep"]
args	Array	命令参数列表	["300"]，表示睡眠 300 秒

9 .请求前必须替换的占位符

占位符文本	所在位置	正确值来源
"指定区域"	resources[0].region_name	调用资源查询 API 返回的 region_name
"根据查讯资源信息所获得"	resources[0].mark	调用资源查询 API 返回的 mark 字段
"指定所使用的镜像地址"	services[0].service_image	自己构建并推送的镜像地址，如 harbor 仓库

10 .发送请求前的检查清单

1. mark 已替换为真实有效的资源标识码
2. service_image 已替换为真实存在的容器镜像地址
3. 如果平台要求 resource_weight 在顶层且为数值，已调整 JSON 结构
4. 如果不需要健康检查，已删除 health_checks 对象
5. resources 的结构符合官方文档，已确认是否允许嵌套 resource 对象
6. 所有字符串值没有包含 Postman 模板语法，例如 {{$timestamp}}

查询指定 job 任务状态

参数解析：

• task_id：任务 id（与平台任务列表中的 id 一致，例如 TASK-2025753-186，task_id 为 2025753）
• token：请填入您在平台内创建的 API 密钥，获取路径为：右上角头像 → API 密钥
• timestamp：时间戳（示例：1770194570564）
• version：固定值（示例：1.0.0）

停止指定 job 任务

参数解析：

• token：请填入您在平台内创建的 API 密钥，获取路径为：右上角头像 → API 密钥
• timestamp：时间戳（示例：1770194570564）
• version：固定值（示例：1.0.0）
• task_id：任务 id（与平台任务列表中的 id 一致，例如 TASK-2025753-186，id 为 2025753）

API 调用注意事项

• API 密钥需妥善保管，若泄露需及时在平台“API 密钥管理”页面重置。
• 调用 API 时，需确保参数正确（如 jobId 需与平台任务列表中的一致），避免因参数错误导致请求失败。
• 若任务处于“运行中”状态，不可重复启动；若需重新执行，需先停止任务，再新建、启动。
• API 调用有频率限制，避免高频调用导致请求被拦截频率限制参数。

四、注意事项

• 镜像构建时，需确保基础镜像与云主机操作系统一致，依赖安装命令适配操作系统，避免镜像无法正常启动。
• 镜像推送至仓库时，需确认仓库地址、用户名、镜像标签正确，否则推送失败。
• job 任务配置时，资源配置需匹配任务需求，资源不足会导致任务执行失败，资源过剩会造成浪费。
• Open API 调用时，若返回 code≠200，可根据 message 提示排查问题（如权限不足、参数错误、任务状态异常等）。
• 任务执行完成后，及时查看任务日志，若有报错，根据日志信息调整镜像或程序，重新构建镜像并执行任务。

五、常见问题排查

• 问题 1：job 任务启动失败？ 排查：检查镜像是否推送成功、镜像标签是否正确、资源配置是否充足，查看任务日志，排查程序运行报错。
• 问题 2：Open API 调用失败？ 排查：检查 API 密钥是否正确、请求头是否完整、请求参数是否符合要求、API 基础地址是否正确，联系平台管理员确认 API 权限。

六、联系客服