# HTTP API

来源：https://mimolive.com/zh/user-manual/remote-control-automation/http-api/  
最后更新：2023-03-08  
章节：远程控制与自动化  

一方面，mimoLive 提供了一个 [远程控制界面](https://mimolive.com/user-manual/remote-control-surfaces)，您可以利用它创建自定义用户界面，并在平板电脑或类似设备上使用该界面远程控制 mimoLive。

此外，mimoLive 还提供了基础 HTTP API 接口，以便您编写自定义脚本（通过 **bash** 和 **curl**、 **AppleScript**、内置的 [自动化层](https://mimolive.com/user-manual/automation) 或任何能够与 HTTP 服务器通信的类似工具），从而控制 mimoLive 的各个方面——其应用可能性几乎无穷无尽。 （参见 [API 使用示例](https://mimolive.com/user-manual/examples-of-api-usage))

在本主题中，我们将重点介绍基础的 HTTP API。由于该 API 基于 [json:api 规范](http://jsonapi.org/)，请务必在使用 mimoLive API 之前熟悉该规范。

\*除了文档之外，您还可以查看我们在 GitHub 上的 PHP 演示脚本

此外，还有适用于 Shell 和 AppleScript 的示例。

#### API 访问

mimoLive API 可在 mimoLive 运行的同一台机器上（通过“localhost”）以及本地网络中（通过“.local”）访问。

若已启用，mimoLive 将在“8989 端口”上提供 HTTP 服务器服务。

所有 API 调用均以路径“/api/v1/”为前缀，例如，若要获取已打开文档的列表，则需调用“http://localhost:8989/api/v1/documents”。

所有 ID（包括文档、图层、源、输出目标等）均存储并持久化到磁盘中，因此只要在 mimoLive 内部使用的是同一文档，硬编码这些值是安全的。

请参阅 [API 端点](https://mimolive.com/user-manual/customization/http-api/endpoints/) 以了解所提供所有端点的详细信息。

#### 身份验证

从 mimoLive 3.1 开始，如果用户在 mimoLive 首选项中启用了身份验证，则每次向 API 发送请求时都需要提供用户密码，可通过以下两种方式实现：

- 设置自定义 HTTP 头“X-MimoLive-Password-SHA256: xxxxxxx”
- 在查询参数后附加“?pwSHA256=xxxxxxx”

无论采用哪种方式，都必须将 xxxxxxx 替换为原始密码（UTF-8 编码），该密码需经过 SHA-256 哈希处理，并编码为十六进制字符串。
为了方便开发自定义脚本和应用程序，mimoLive 会在“远程控制“首选项面板中显示此 API 密钥，并允许将其复制到剪贴板：

![](https://mimolive.com/wp-content/uploads/2023/03/dddc6bf5-964b-493c-b35e-ee5b37e44e40.png)

##### 已弃用的身份验证方法

在 mimoLive 3.1 版本之前，针对 API 的请求会通过在每次请求中使用特殊的 HTTP 头“X-MimoLive-Password:”或查询参数"?pw="来进行身份验证。
遗憾的是，此方法会通过潜在不安全的网络连接以明文形式传输密码，若该 HTTP API 密码在其他地方被重复使用，可能会导致敏感数据泄露。
尽管该身份验证方法目前仍可正常工作，但我们不建议使用，且未来可能会被移除。

#### 错误

如果请求过程中发生错误，mimoLive 将停止处理该请求，并返回一个包含错误状态码的 HTTP 响应。该响应还包含一个 JSON 有效载荷数组，其中包含错误对象，这些对象包含关于每个发生错误的详细信息：

```
{
  "errors": [
    {
 "status": "404",
 "title": "未找到",
 "description": "无法找到请求的对象"
    }
  ]
}
```

#### 通过互联网进行远程访问

由于 HTTP API 由 mimoLive 内置的 Web 服务器提供支持，因此只要为 mimoLive 计算机分配一个公共 IP 地址，即可从互联网上的任何位置远程访问该 HTTP API。但鉴于 HTTP API 的安全防护措施并不完善，这种做法并不推荐。 通过公共网络启用对 HTTP API 的远程访问的更好方法是 [使用 ngrok 与您的 mimoLive 主机建立安全隧道](https://mimolive.com/user-manual/access-remote-control-surfaces-and-http-api-remotely)。

## 本节中的页面

- [端点](https://mimolive.com/zh/user-manual/remote-control-automation/http-api/endpoints/.md)
- [数据类型](https://mimolive.com/zh/user-manual/remote-control-automation/http-api/data-types/.md)
- [API 使用示例](https://mimolive.com/zh/user-manual/remote-control-automation/http-api/examples-of-api-usage/.md)