API 参考

通过标准化的 RESTful 接口部署并执行您的 函数。

执行端点

POST https://api.matesst.com/api/v2/:functionName

将 :functionName 替换为您想要执行的 函数名称。

请求头 (Headers)

Header	Value	描述
Authorization	Bearer ${API_SECRET}	您的应用密钥
Content-Type	application/json	JSON 格式正文必填

请求体 (Request Body)

请求体必须是一个包含以下字段的 JSON 对象：

字段	类型	必填	描述
params	Array	是	函数的输入参数列表。
nargout	Number	是	函数预期的返回值数量。
instanceId	String	否	指定使用的算法机器 ID。

理解 instanceId

• 负载均衡: 如果省略 instanceId，Matesst 将从共享池（ID 以 instance- 开头）中选择一台机器，使用复杂的负载均衡算法进行分配。
• 专属实例 (Dedicated Instance): 您可以指定自定义字符串作为 instanceId。如果该 ID 不存在，Matesst 将自动启动一台独立于共享负载均衡池的临时专用机器。这确保了您的进程在并发情况下不会被其他请求抢占或干扰，提供更稳定的资源保障。
• 性能优化: 对后续请求复用同一个 instanceId 可以避免冷启动时间，因为该 ID 对应的机器会保持“热”状态。

请求示例

{
  "params": [1, 2],
  "nargout": 1,
  "instanceId": "instance-0"
}

---

响应结构

Matesst 返回一个包含执行结果的 JSON 对象。

字段	类型	描述
results	any	函数的返回值。
status	String	请求状态（例如 "success", "error"）。

结果包装规则

• nargout = 1 且结果为单个数字: 如果函数返回单个数字且 nargout 设置为 1，它将直接在 results 字段中返回。
• 其他情况: 结果始终被包装在嵌套数组结构中。外层数组的长度对应于 nargout。
  • 示例: 如果 nargout = 1 且函数返回数组 [1, 2, 3]，results 字段将为 [[1, 2, 3]]。

示例：单个数字

{
  "results": 7,
  "status": "success"
}

示例：复杂数据（unique 函数）

当调用返回多个向量或矩阵的函数（如 unique）时，每个输出都会根据其维度进行包装。请注意行向量（第一个结果）与列向量（第二个和第三个结果）在 JSON 结构上的差异。

请求：

{
  "params": [[9, 2, 2, 9, 5]],
  "nargout": 3
}

响应：

{
  "results": [
    [[2, 5, 9]], // 输出 1: 唯一值 (行向量)
    [[2], [5], [1]], // 输出 2: 索引 ia (列向量)
    [[3], [1], [1], [3], [2]] // 输出 3: 反向索引 ic (列向量)
  ],
  "status": "success"
}

---

错误处理

如果执行失败，Matesst 将返回非 200 的状态码，并在 JSON 正文中描述错误信息。

字段	类型	描述
error	String	错误类型的简要摘要。
message	String	详细的错误信息，通常包含 堆栈轨迹。

错误响应示例

{
  "error": "Execution Error",
  "message": "Too many input arguments.\n"
}