> For the complete documentation index, see [llms.txt](https://scx.gitbook.io/sc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scx.gitbook.io/sc/scp-docs/api-wen-dang/ren-wu.md).
# 任务
测试任务管理
## 获取任务列表
> 返回当前用户任务的分页列表。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"PagedTaskResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TaskStatus"},"type":"array"},"page":{"format":"int32","type":"integer"},"page_size":{"format":"int32","type":"integer"},"total":{"format":"int64","type":"integer"}},"type":"object"},"TaskStatus":{"properties":{"completed_at":{"description":"任务完成时间。未完成的任务该字段为 null。","format":"date-time","type":"string"},"completed_nodes":{"description":"当前已完成测试的节点数量。","format":"int32","type":"integer"},"created_at":{"description":"任务创建时间。","format":"date-time","type":"string"},"credit_cost":{"description":"任务消耗的积分数量。","format":"int64","type":"integer"},"duration_ms":{"description":"任务持续时间，单位毫秒。","format":"int64","type":"integer"},"error_msg":{"description":"任务失败时的错误信息。","type":"string"},"macros":{"description":"任务使用的测试宏列表，详情请查看任务定义。","items":{"type":"string","enum":["SPEED","PING","UDP","SCRIPT","GEO","TRACEROUTE","LONGCONN","HIJACK","INVALID"]},"type":"array"},"name":{"description":"人类可读的任务名称。","type":"string"},"node_count":{"description":"任务包含的节点数量。","format":"int32","type":"integer"},"runner_completed_at_ms":{"description":"任务完成时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_created_at_ms":{"description":"任务创建时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_started_at_ms":{"description":"任务开始时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"service_type":{"description":"调用任务的套餐类型。","type":"string"},"slave_id":{"description":"执行该任务的后端 ID。","type":"string"},"slave_name":{"description":"执行该任务的后端显示名称。","type":"string"},"started_at":{"description":"任务开始时间。","format":"date-time","type":"string"},"status":{"enum":["pending","running","completed","failed","canceled","unspecified"],"type":"string"},"task_id":{"format":"uuid","type":"string"},"type":{"type":"string"},"user_id":{"format":"int64","type":"integer"}},"type":"object"}}},"paths":{"/api/v1/tasks":{"get":{"description":"返回当前用户任务的分页列表。","parameters":[{"in":"query","name":"page","schema":{"default":1,"type":"integer"}},{"in":"query","name":"page_size","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"status","schema":{"enum":["pending","running","completed","failed","canceled"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/PagedTaskResponse"}},"type":"object"}]}}},"description":"任务列表。"},"401":{"description":"API Key 无效。"}},"summary":"获取任务列表","tags":["任务"]}}}}
```
## 提交任务
> 提交一个新的测试任务。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"TaskRequestConfigs":{"description":"测试配置项。兼容 Miaospeed 的 SlaveRequestConfigs。","properties":{"Scripts":{"description":"脚本库，可在 TEST_SCRIPT Matrix 中或者在 GeoIP 测试中调用。","items":{"properties":{"ID":{"description":"脚本唯一标识。在脚本类型为 media 时须与矩阵项中的 Params 对应。","type":"string"},"content":{"description":"在引擎内执行的 JavaScript 源码。详情请查看脚本教程。","type":"string"},"timeout":{"description":"执行超时时间，单位毫秒。","format":"int64","type":"integer"},"type":{"description":"脚本类型：media（流媒体解锁）或 ip（IP 信息查询），详情请查看脚本教程。","enum":["media","ip"],"type":"string"}},"type":"object"},"type":"array"},"dnsServers":{"items":{"type":"string"},"type":"array"},"downloadDuration":{"description":"测速时长，单位秒。","format":"int64","type":"integer"},"downloadThreading":{"description":"测速线程数。","type":"integer"},"downloadURL":{"type":"string"},"pingAddress":{"type":"string"},"pingAverageOver":{"description":"参与均值计算的 Ping 次数。","type":"integer"},"stunURL":{"type":"string"},"taskRetry":{"type":"integer"},"tracerouteMaxHops":{"description":"Traceroute 最大跳数。默认值：30。","type":"integer"},"tracerouteProbesPerHop":{"description":"每一跳的探测次数。默认值：3。","type":"integer"},"tracerouteTimeout":{"description":"每一跳探测超时，单位秒。0 表示使用全局任务超时。","type":"integer"}},"type":"object"},"TaskRequestMatrixEntry":{"description":"单个请求的测试矩阵项。","properties":{"Params":{"description":"矩阵参数，在 TEST_SCRIPT 类型的 Matrix 中代表要使用的脚本 ID。","type":"string"},"Type":{"description":"矩阵类型。","$ref":"#/components/schemas/TaskRequestMatrixType","type":"string"}},"type":"object"},"TaskRequestMatrixType":{"description":"矩阵类型标识。","enum":["SPEED_AVERAGE","SPEED_MAX","SPEED_PER_SECOND","UDP_TYPE","GEOIP_INBOUND","GEOIP_OUTBOUND","TEST_SCRIPT","TEST_PING_CONN","TEST_PING_RTT","TRACEROUTE","LONGCONN","TEST_PING_MAX_RTT","TEST_PING_TOTAL_CONN","TEST_PING_TOTAL_RTT","TEST_PING_SD_RTT","TEST_PING_SD_CONN","TEST_HTTP_CODE","TEST_PING_PACKET_LOSS","TEST_HIJACK_DETECTION","INVALID"],"type":"string"},"Node":{"description":"测试请求中提交的节点。","properties":{"Name":{"type":"string"},"Payload":{"description":"Clash YAML 类型的代理信息","type":"string"}},"type":"object"},"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"InsufficientCreditData":{"description":"提交任务返回业务错误码 50001 时，若计费信息可用则返回该数据。","properties":{"remaining_credit":{"description":"当前套餐剩余积分。","format":"int64","type":"integer"},"required_credit":{"description":"本次任务需要的积分。","format":"int64","type":"integer"}},"required":["required_credit","remaining_credit"],"type":"object"}}},"paths":{"/api/v1/tasks":{"post":{"description":"提交一个新的测试任务。\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"configs":{"allOf":[{"$ref":"#/components/schemas/TaskRequestConfigs"}],"description":"测试配置，同 Miaospeed 的 SlaveRequestConfigs。"},"matrices":{"description":"要运行的测试矩阵列表，同 Miaospeed 的 SlaveRequestMatrixEntry。","items":{"$ref":"#/components/schemas/TaskRequestMatrixEntry"},"type":"array"},"name":{"description":"人类可读的任务名称。","maxLength":128,"minLength":1,"type":"string"},"nodes":{"description":"Clash YAML 格式的节点列表，同 Miaospeed 的 []SlaveRequestNode。","items":{"$ref":"#/components/schemas/Node"},"type":"array"},"slave_id":{"description":"Slave ID，未指定则从后端列表中自动挑选一个可用后端。","type":"string"}},"required":["name","nodes","matrices"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"properties":{"status":{"type":"string"},"task_id":{"format":"uuid","type":"string"}},"type":"object"}},"type":"object"}]}}},"description":"任务已提交。"},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/InsufficientCreditData"}},"type":"object"}]}}},"description":"请求参数无效，或积分不足（50001）。积分不足且计费信息可用时，data 包含所需积分和剩余积分。"},"401":{"description":"缺少或无效的 API Key。"},"403":{"description":"API 未启用、缺少可访问 API 的套餐，或节点数/矩阵数超过套餐配额限制。"}},"summary":"提交任务","tags":["任务"]}}}}
```
## 获取任务详情
> 返回当前任务状态。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"TaskStatus":{"properties":{"completed_at":{"description":"任务完成时间。未完成的任务该字段为 null。","format":"date-time","type":"string"},"completed_nodes":{"description":"当前已完成测试的节点数量。","format":"int32","type":"integer"},"created_at":{"description":"任务创建时间。","format":"date-time","type":"string"},"credit_cost":{"description":"任务消耗的积分数量。","format":"int64","type":"integer"},"duration_ms":{"description":"任务持续时间，单位毫秒。","format":"int64","type":"integer"},"error_msg":{"description":"任务失败时的错误信息。","type":"string"},"macros":{"description":"任务使用的测试宏列表，详情请查看任务定义。","items":{"type":"string","enum":["SPEED","PING","UDP","SCRIPT","GEO","TRACEROUTE","LONGCONN","HIJACK","INVALID"]},"type":"array"},"name":{"description":"人类可读的任务名称。","type":"string"},"node_count":{"description":"任务包含的节点数量。","format":"int32","type":"integer"},"runner_completed_at_ms":{"description":"任务完成时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_created_at_ms":{"description":"任务创建时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_started_at_ms":{"description":"任务开始时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"service_type":{"description":"调用任务的套餐类型。","type":"string"},"slave_id":{"description":"执行该任务的后端 ID。","type":"string"},"slave_name":{"description":"执行该任务的后端显示名称。","type":"string"},"started_at":{"description":"任务开始时间。","format":"date-time","type":"string"},"status":{"enum":["pending","running","completed","failed","canceled","unspecified"],"type":"string"},"task_id":{"format":"uuid","type":"string"},"type":{"type":"string"},"user_id":{"format":"int64","type":"integer"}},"type":"object"}}},"paths":{"/api/v1/tasks/{taskId}":{"get":{"description":"返回当前任务状态。","parameters":[{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/TaskStatus"}},"type":"object"}]}}},"description":"任务详情。"},"401":{"description":"API Key 无效。"},"404":{"description":"任务未找到。"}},"summary":"获取任务详情","tags":["任务"]}}}}
```
## 取消任务
> 请求取消一个等待中或运行中的任务。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}}},"paths":{"/api/v1/tasks/{taskId}":{"delete":{"description":"请求取消一个等待中或运行中的任务。","parameters":[{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"已发起取消请求。"},"401":{"description":"API Key 无效。"},"404":{"description":"任务未找到。"}},"summary":"取消任务","tags":["任务"]}}}}
```
## 导出任务图片
> 将任务结果导出为图片。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}}},"paths":{"/api/v1/tasks/{taskId}/export/{type}":{"get":{"description":"将任务结果导出为图片。\n","parameters":[{"description":"任务 UUID。","in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"导出视图类型。NormalView 适用于大多数测试，TopologyView 适用于拓扑分析测试（需要 GEOIP_INBOUND 和 GEOIP_OUTBOUND 矩阵）","in":"path","name":"type","required":true,"schema":{"enum":["normalview","topologyview"],"type":"string"}},{"description":"行排序顺序，仅适用于 `normalview`。\n零值 / 失败值始终排在最后。\n","in":"query","name":"sort","required":false,"schema":{"enum":["name_asc","name_desc","rtt_asc","rtt_desc","https_asc","https_desc","avg_speed_asc","avg_speed_desc","max_speed_asc","max_speed_desc"],"type":"string"}}],"responses":{"200":{"content":{"image/jpeg":{"schema":{"format":"binary","type":"string"}},"image/png":{"schema":{"format":"binary","type":"string"}}},"description":"渲染后的图片。"},"401":{"description":"API Key 无效。"},"403":{"description":"当前套餐不支持图片导出功能。"},"422":{"description":"任务未完成、矩阵数据缺失或渲染失败。"}},"summary":"导出任务图片","tags":["任务"]}}}}
```
## 获取任务进度
> 返回运行中任务的实时进度。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"TaskProgress":{"description":"任务进度。包含当前完成测试的节点信息。","properties":{"completed_count":{"description":"当前已完成测试的节点数量。","format":"int32","type":"integer"},"entries":{"description":"按结果产生顺序排列的逐节点结果项，同 Miaospeed 的 []SlaveEntrySlot。","items":{"$ref":"#/components/schemas/TaskRequestEntrySlot"},"type":"array"},"task_id":{"description":"任务 UUID。","format":"uuid","type":"string"},"total_count":{"description":"该任务的总节点数。","format":"int32","type":"integer"}},"type":"object"},"TaskRequestEntrySlot":{"description":"单个代理节点的测试结果，同 Miaospeed 的 SlaveEntrySlot。","properties":{"Grouping":{"description":"可选的节点分组标签。","type":"string"},"InvokeDuration":{"description":"该节点测试总耗时，单位毫秒。","format":"int64","type":"integer"},"Matrices":{"description":"与原始请求顺序一致的矩阵结果列表，同 Miaospeed 的 []MatrixResponse。","items":{"$ref":"#/components/schemas/TaskRequestMatrixResponse"},"type":"array"},"ProxyInfo":{"$ref":"#/components/schemas/TaskRequestProxyInfo"}},"type":"object"},"TaskRequestMatrixResponse":{"description":"单个测试矩阵结果，同 Miaospeed 的 MatrixResponse，Payload 类型根据 Type 字段而定。请参阅 Payload 字段的描述。\n","properties":{"Payload":{"description":"JSON 编码的指标结果。请按 `Type` 进行解析：\n- **SPEED_AVERAGE** → `{\"Value\": }`\n- **SPEED_MAX** → `{\"Value\": }`\n- **SPEED_PER_SECOND** → `{\"Max\": , \"Average\": , \"Speeds\": [, ...]}`\n- **UDP_TYPE** → `{\"Value\": \"\"}` (e.g. `\"Full Cone\"`, `\"Unknown\"`)\n- **TEST_PING_CONN** → `{\"Value\": }` (HTTP connect ping)\n- **TEST_PING_RTT** → `{\"Value\": }` (round-trip time)\n- **TEST_PING_MAX_RTT** → `{\"Value\": }` (max RTT across all probes)\n- **TEST_PING_TOTAL_CONN** → `{\"Value\": }` (total HTTP connect ping sum)\n- **TEST_PING_TOTAL_RTT** → `{\"Value\": }` (total RTT sum)\n- **TEST_PING_SD_RTT** → `{\"Value\": }` (RTT standard deviation in ms)\n- **TEST_PING_SD_CONN** → `{\"Value\": }` (HTTP connect standard deviation in ms)\n- **TEST_HTTP_CODE** → `{\"Values\": [, ...]}` (HTTP status codes observed)\n- **TEST_PING_PACKET_LOSS** → `{\"Value\": }` (packet loss ratio 0.00 - 100.00)\n- **TEST_HIJACK_DETECTION** → `{\"SpeedIP\": \"\", \"RealIP\": \"\"}` (SpeedIP == RealIP means no hijack)\n- **TEST_SCRIPT** → `{\"Key\": \"\", \"Text\": \"\", \"Color\": \"\", \"Background\": \"\", \"TimeElapsed\": }` \n- **GEOIP_INBOUND** → See `MultiStacks` schema (inbound/client-side IP geo)\n- **GEOIP_OUTBOUND** → See `MultiStacks` schema (outbound/exit-node IP geo)\n- **TRACEROUTE** → See `TraceRouteDS` schema\n- **LONGCONN** → See `LongConnDS` schema\n","type":"string"},"Type":{"description":"矩阵类型标识。","$ref":"#/components/schemas/TaskRequestMatrixType"}},"type":"object"},"TaskRequestMatrixType":{"description":"矩阵类型标识。","enum":["SPEED_AVERAGE","SPEED_MAX","SPEED_PER_SECOND","UDP_TYPE","GEOIP_INBOUND","GEOIP_OUTBOUND","TEST_SCRIPT","TEST_PING_CONN","TEST_PING_RTT","TRACEROUTE","LONGCONN","TEST_PING_MAX_RTT","TEST_PING_TOTAL_CONN","TEST_PING_TOTAL_RTT","TEST_PING_SD_RTT","TEST_PING_SD_CONN","TEST_HTTP_CODE","TEST_PING_PACKET_LOSS","TEST_HIJACK_DETECTION","INVALID"],"type":"string"},"TaskRequestProxyInfo":{"description":"节点信息，同 Miaospeed 的 ProxyInfo。","properties":{"Address":{"description":"节点地址，格式 host:port。","type":"string"},"Name":{"description":"节点名称。","type":"string"},"Type":{"description":"代理协议类型。以下是 SpeedCentre+ 目前支持测试的节点协议。","enum":["Shadowsocks","ShadowsocksR","Snell","Socks5","Http","Vmess","Trojan","Vless","Hysteria","Hysteria2","Tuic","Wireguard","AnyTLS","Mieru"],"type":"string"}},"type":"object"}}},"paths":{"/api/v1/tasks/{taskId}/progress":{"get":{"description":"返回运行中任务的实时进度。","parameters":[{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/TaskProgress"}},"type":"object"}]}}},"description":"进度数据。"},"401":{"description":"API Key 无效。"},"404":{"description":"任务未找到。"}},"summary":"获取任务进度","tags":["任务"]}}}}
```
## 获取任务结果
> 返回已完成任务的完整任务结果与任务状态。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"TaskResult":{"description":"任务结果。同 Miaospeed 的 SlaveTask。","properties":{"result":{"$ref":"#/components/schemas/Task","description":"完整的 miaospeed 测试结果。结果不可用时返回空的 SlaveTask。"},"task":{"$ref":"#/components/schemas/TaskStatus","description":"供前端任务详情页使用的任务元数据。"},"task_id":{"description":"任务 UUID。","format":"uuid","type":"string"}},"type":"object"},"Task":{"description":"完整的测试结果数据结构。同 Miaospeed 的 SlaveTask。\n","properties":{"Request":{"$ref":"#/components/schemas/TaskRequest","description":"原始测试请求。"},"Results":{"description":"节点测试结果。","items":{"$ref":"#/components/schemas/TaskRequestEntrySlot"},"type":"array"}},"type":"object"},"TaskRequest":{"description":"任务请求，同 Miaospeed 的 SlaveRequest。\n","properties":{"Basics":{"$ref":"#/components/schemas/TaskRequestBasics"},"Configs":{"$ref":"#/components/schemas/TaskRequestConfigs"},"Nodes":{"items":{"$ref":"#/components/schemas/Node"},"type":"array"},"Options":{"$ref":"#/components/schemas/TaskRequestOptions"},"Vendor":{"type":"string"}},"type":"object"},"TaskRequestBasics":{"description":"任务基本信息，同 Miaospeed 的 SlaveRequestBasics","properties":{"ID":{"type":"string"},"Invoker":{"type":"string"},"Slave":{"type":"string"},"SlaveName":{"type":"string"},"Version":{"type":"string"},"Weight":{"description":"任务优先级，由您发起任务的套餐决定，优先级越高的任务在后端繁忙时运行的更快。","type":"integer"}},"type":"object"},"TaskRequestConfigs":{"description":"测试配置项。兼容 Miaospeed 的 SlaveRequestConfigs。","properties":{"Scripts":{"description":"脚本库，可在 TEST_SCRIPT Matrix 中或者在 GeoIP 测试中调用。","items":{"properties":{"ID":{"description":"脚本唯一标识。在脚本类型为 media 时须与矩阵项中的 Params 对应。","type":"string"},"content":{"description":"在引擎内执行的 JavaScript 源码。详情请查看脚本教程。","type":"string"},"timeout":{"description":"执行超时时间，单位毫秒。","format":"int64","type":"integer"},"type":{"description":"脚本类型：media（流媒体解锁）或 ip（IP 信息查询），详情请查看脚本教程。","enum":["media","ip"],"type":"string"}},"type":"object"},"type":"array"},"dnsServers":{"items":{"type":"string"},"type":"array"},"downloadDuration":{"description":"测速时长，单位秒。","format":"int64","type":"integer"},"downloadThreading":{"description":"测速线程数。","type":"integer"},"downloadURL":{"type":"string"},"pingAddress":{"type":"string"},"pingAverageOver":{"description":"参与均值计算的 Ping 次数。","type":"integer"},"stunURL":{"type":"string"},"taskRetry":{"type":"integer"},"tracerouteMaxHops":{"description":"Traceroute 最大跳数。默认值：30。","type":"integer"},"tracerouteProbesPerHop":{"description":"每一跳的探测次数。默认值：3。","type":"integer"},"tracerouteTimeout":{"description":"每一跳探测超时，单位秒。0 表示使用全局任务超时。","type":"integer"}},"type":"object"},"Node":{"description":"测试请求中提交的节点。","properties":{"Name":{"type":"string"},"Payload":{"description":"Clash YAML 类型的代理信息","type":"string"}},"type":"object"},"TaskRequestOptions":{"description":"请求中包含的矩阵选择与过滤选项。","properties":{"Filter":{"description":"节点名称过滤正则。API 不负责对节点进行过滤操作","type":"string"},"Matrices":{"description":"测试矩阵列表。","items":{"$ref":"#/components/schemas/TaskRequestMatrixEntry"},"type":"array"}},"type":"object"},"TaskRequestMatrixEntry":{"description":"单个请求的测试矩阵项。","properties":{"Params":{"description":"矩阵参数，在 TEST_SCRIPT 类型的 Matrix 中代表要使用的脚本 ID。","type":"string"},"Type":{"description":"矩阵类型。","$ref":"#/components/schemas/TaskRequestMatrixType","type":"string"}},"type":"object"},"TaskRequestMatrixType":{"description":"矩阵类型标识。","enum":["SPEED_AVERAGE","SPEED_MAX","SPEED_PER_SECOND","UDP_TYPE","GEOIP_INBOUND","GEOIP_OUTBOUND","TEST_SCRIPT","TEST_PING_CONN","TEST_PING_RTT","TRACEROUTE","LONGCONN","TEST_PING_MAX_RTT","TEST_PING_TOTAL_CONN","TEST_PING_TOTAL_RTT","TEST_PING_SD_RTT","TEST_PING_SD_CONN","TEST_HTTP_CODE","TEST_PING_PACKET_LOSS","TEST_HIJACK_DETECTION","INVALID"],"type":"string"},"TaskRequestEntrySlot":{"description":"单个代理节点的测试结果，同 Miaospeed 的 SlaveEntrySlot。","properties":{"Grouping":{"description":"可选的节点分组标签。","type":"string"},"InvokeDuration":{"description":"该节点测试总耗时，单位毫秒。","format":"int64","type":"integer"},"Matrices":{"description":"与原始请求顺序一致的矩阵结果列表，同 Miaospeed 的 []MatrixResponse。","items":{"$ref":"#/components/schemas/TaskRequestMatrixResponse"},"type":"array"},"ProxyInfo":{"$ref":"#/components/schemas/TaskRequestProxyInfo"}},"type":"object"},"TaskRequestMatrixResponse":{"description":"单个测试矩阵结果，同 Miaospeed 的 MatrixResponse，Payload 类型根据 Type 字段而定。请参阅 Payload 字段的描述。\n","properties":{"Payload":{"description":"JSON 编码的指标结果。请按 `Type` 进行解析：\n- **SPEED_AVERAGE** → `{\"Value\": }`\n- **SPEED_MAX** → `{\"Value\": }`\n- **SPEED_PER_SECOND** → `{\"Max\": , \"Average\": , \"Speeds\": [, ...]}`\n- **UDP_TYPE** → `{\"Value\": \"\"}` (e.g. `\"Full Cone\"`, `\"Unknown\"`)\n- **TEST_PING_CONN** → `{\"Value\": }` (HTTP connect ping)\n- **TEST_PING_RTT** → `{\"Value\": }` (round-trip time)\n- **TEST_PING_MAX_RTT** → `{\"Value\": }` (max RTT across all probes)\n- **TEST_PING_TOTAL_CONN** → `{\"Value\": }` (total HTTP connect ping sum)\n- **TEST_PING_TOTAL_RTT** → `{\"Value\": }` (total RTT sum)\n- **TEST_PING_SD_RTT** → `{\"Value\": }` (RTT standard deviation in ms)\n- **TEST_PING_SD_CONN** → `{\"Value\": }` (HTTP connect standard deviation in ms)\n- **TEST_HTTP_CODE** → `{\"Values\": [, ...]}` (HTTP status codes observed)\n- **TEST_PING_PACKET_LOSS** → `{\"Value\": }` (packet loss ratio 0.00 - 100.00)\n- **TEST_HIJACK_DETECTION** → `{\"SpeedIP\": \"\", \"RealIP\": \"\"}` (SpeedIP == RealIP means no hijack)\n- **TEST_SCRIPT** → `{\"Key\": \"\", \"Text\": \"\", \"Color\": \"\", \"Background\": \"\", \"TimeElapsed\": }` \n- **GEOIP_INBOUND** → See `MultiStacks` schema (inbound/client-side IP geo)\n- **GEOIP_OUTBOUND** → See `MultiStacks` schema (outbound/exit-node IP geo)\n- **TRACEROUTE** → See `TraceRouteDS` schema\n- **LONGCONN** → See `LongConnDS` schema\n","type":"string"},"Type":{"description":"矩阵类型标识。","$ref":"#/components/schemas/TaskRequestMatrixType"}},"type":"object"},"TaskRequestProxyInfo":{"description":"节点信息，同 Miaospeed 的 ProxyInfo。","properties":{"Address":{"description":"节点地址，格式 host:port。","type":"string"},"Name":{"description":"节点名称。","type":"string"},"Type":{"description":"代理协议类型。以下是 SpeedCentre+ 目前支持测试的节点协议。","enum":["Shadowsocks","ShadowsocksR","Snell","Socks5","Http","Vmess","Trojan","Vless","Hysteria","Hysteria2","Tuic","Wireguard","AnyTLS","Mieru"],"type":"string"}},"type":"object"},"TaskStatus":{"properties":{"completed_at":{"description":"任务完成时间。未完成的任务该字段为 null。","format":"date-time","type":"string"},"completed_nodes":{"description":"当前已完成测试的节点数量。","format":"int32","type":"integer"},"created_at":{"description":"任务创建时间。","format":"date-time","type":"string"},"credit_cost":{"description":"任务消耗的积分数量。","format":"int64","type":"integer"},"duration_ms":{"description":"任务持续时间，单位毫秒。","format":"int64","type":"integer"},"error_msg":{"description":"任务失败时的错误信息。","type":"string"},"macros":{"description":"任务使用的测试宏列表，详情请查看任务定义。","items":{"type":"string","enum":["SPEED","PING","UDP","SCRIPT","GEO","TRACEROUTE","LONGCONN","HIJACK","INVALID"]},"type":"array"},"name":{"description":"人类可读的任务名称。","type":"string"},"node_count":{"description":"任务包含的节点数量。","format":"int32","type":"integer"},"runner_completed_at_ms":{"description":"任务完成时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_created_at_ms":{"description":"任务创建时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"runner_started_at_ms":{"description":"任务开始时间，Unix 时间戳，单位毫秒。","format":"int64","type":"integer"},"service_type":{"description":"调用任务的套餐类型。","type":"string"},"slave_id":{"description":"执行该任务的后端 ID。","type":"string"},"slave_name":{"description":"执行该任务的后端显示名称。","type":"string"},"started_at":{"description":"任务开始时间。","format":"date-time","type":"string"},"status":{"enum":["pending","running","completed","failed","canceled","unspecified"],"type":"string"},"task_id":{"format":"uuid","type":"string"},"type":{"type":"string"},"user_id":{"format":"int64","type":"integer"}},"type":"object"}}},"paths":{"/api/v1/tasks/{taskId}/result":{"get":{"description":"返回已完成任务的完整任务结果与任务状态。","parameters":[{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/TaskResult"}},"type":"object"}]}}},"description":"任务结果。"},"401":{"description":"API Key 无效。"},"404":{"description":"任务不存在或尚未完成。"}},"summary":"获取任务结果","tags":["任务"]}}}}
```
## 创建任务分享
> 为任务创建公开分享链接。
```json
{"openapi":"3.0.3","info":{"title":"SpeedCentre+ 用户 API","version":"1.0"},"tags":[{"description":"测试任务管理","name":"任务"}],"servers":[{"description":"用户 API 服务","url":"https://api.speedcentre.plus"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"API Key。","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{"APIResponse":{"properties":{"code":{"description":"0 表示成功；其他值表示业务错误码。","type":"integer"},"data":{"description":"返回载荷；成功时存在，部分错误会包含结构化详情。"},"message":{"type":"string"}},"type":"object"},"TaskShare":{"properties":{"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","type":"string"},"hide_private_info":{"type":"boolean"},"is_active":{"type":"boolean"},"task_id":{"format":"uuid","type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"},"user_id":{"format":"int64","type":"integer"},"uuid":{"format":"uuid","type":"string"}},"type":"object"}}},"paths":{"/api/v1/tasks/{taskId}/share":{"post":{"description":"为任务创建公开分享链接。","parameters":[{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expires_at":{"format":"int64","type":"integer"},"hide_private_info":{"type":"boolean","description":"是否隐藏任务结果中的敏感信息（如节点地址等）。"},"title":{"maxLength":128,"minLength":1,"type":"string"}},"required":["title"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"properties":{"data":{"$ref":"#/components/schemas/TaskShare"}},"type":"object"}]}}},"description":"分享已创建。"},"400":{"description":"请求参数无效。"},"401":{"description":"API Key 无效。"}},"summary":"创建任务分享","tags":["任务"]}}}}
```