> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overleaf 导入 API

### "Overleaf 导入 API"功能

从 Ayakaleaf Pro v6.3 开始，你可以创建链接，从某个 URL 导入 LaTeX 文件或 zip 压缩的项目，并在你自己的 Ayakaleaf 实例中打开它，类似于 Overleaf 的 ["Open in Overleaf" API](https://cn.overleaf.com/devs)。

此功能默认启用，你只需访问 `your.overleaf.com/devs` 即可查看详细页面和说明。

<Info>
  除非设置了 `OVERLEAF_ALLOW_PUBLIC_ACCESS=true`，否则访问 `/devs` 页面需要登录，请参阅[未登录访客](/zh-CN/on-premises/configuration/overleaf-toolkit/overleaf-import-api#signed-out-visitors "mention")。
</Info>

<Frame>
  <img src="https://mintcdn.com/ayakaleaf-pro/Wx0mJ_Lfqd9J3VFX/images/on-premises/image-51.png?fit=max&auto=format&n=Wx0mJ_Lfqd9J3VFX&q=85&s=5ba20ae774c684ce71df33d454bda528" alt="" width="2102" height="600" data-path="images/on-premises/image-51.png" />
</Frame>

例如，如果你在 `https://example.com/main.tex` 托管了一个 LaTeX 文件，或在 `https://example.com/project.zip` 托管了一个完整项目，你可以创建一个链接，将其导入到你自己的 Ayakaleaf Pro 实例中并打开新项目：

<Tabs>
  <Tab title="LaTeX 文件">
    ```text wrap theme={null}
    https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fmain.tex
    ```
  </Tab>

  <Tab title="ZIP 项目">
    ```text wrap theme={null}
    https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fproject.zip
    ```
  </Tab>
</Tabs>

请将 `ayakaleaf.example.com` 替换为你的实例域名。

#### 在 Ayakaleaf Pro 中打开 LaTeX 项目

从 Ayakaleaf Pro v6.3 开始，你可以创建一个链接，将 LaTeX 文件或 zip 压缩的项目导入到你自己的 Ayakaleaf Pro 实例中。当有人打开该链接时，Ayakaleaf Pro 会根据所提供的文件创建一个新项目，并在编辑器中打开它。

将链接指向你的实例的 `/docs` 端点：

| 参数 | 描述 | 示例 |
| - | - | - |
| `snip_uri` | 要导入的 LaTeX 文件的 URL。也接受单个 ZIP 文件，但对于项目请使用 `zip_uri`。 | `https://example.com/main.tex` |
| `zip_uri` | 要导入的 zip 压缩 LaTeX 项目的 URL。 | `https://example.com/project.zip` |
| `snip_uri[]` | 通过重复此参数导入多个文件。 | `snip_uri[]=.../main.tex&snip_uri[]=.../refs.bib` |
| `snip_name[]` | 按相同顺序为每个 `snip_uri[]` 设置文件名。 | `snip_name[]=main.tex` |
| `engine` | 设置编译器：`latex_dvipdf`、`pdflatex`、`xelatex` 或 `lualatex`。 | `engine=xelatex` |
| `main_document` | 设置导入项目中的主 `.tex` 文件。 | `main_document=main.tex` |
| `name` | 设置新项目的名称。也接受 `project_name`。 | `name=My%20Project` |

例如，如果你的文件托管在 `example.com` 上，这些链接会将它们导入到托管在 `ayakaleaf.example.com` 的 Ayakaleaf Pro 实例中。

#### 使用 Base64 导入项目

你可以将 LaTeX 文件或 zip 压缩的项目以 Base64 data URL 的形式直接嵌入到"Open in Ayakaleaf"链接中。这样无需将文件托管在单独的 URL 上，即可创建导入链接。

| 内容 | 参数 | Data URL 格式 |
| - | - | - |
| LaTeX 文件 | `snip_uri` | `data:application/x-tex;base64,<base64-encoded-tex>` |
| zip 压缩项目 | `zip_uri` | `data:application/zip;base64,<base64-encoded-zip>` |

要导入 ZIP 项目，请对 ZIP 文件进行 Base64 编码，并改为通过 `zip_uri` 传递。构造任一链接时，请对完整的 data URL 使用 `encodeURIComponent`。对于大型项目，请使用托管的 ZIP URL，因为浏览器和服务器的 URL 长度限制可能会使 Base64 链接难以使用。

#### 添加"Open in Ayakaleaf"按钮

你可以使用 HTML 表单，在访客点击按钮时导入文件。使用 `method="post"` 将表单提交到你的实例的 `/docs` 端点。

对于托管的 LaTeX 文件：

```text theme={null}
<form action="https://ayakaleaf.example.com/docs" method="post" target="_blank">
  <input type="hidden" name="snip_uri" value="https://example.com/main.tex">
  <input type="hidden" name="engine" value="xelatex">
  <button type="submit">Open in Ayakaleaf</button>
</form>
```

要导入 zip 压缩的项目，请将 `snip_uri` 替换为 `zip_uri`，并将其指向 ZIP 文件。你也可以直接提交 LaTeX 源码：使用 `snip` 提交原始文本，或使用 `encoded_snip` 提交 URL 编码的文本。

请将 `ayakaleaf.example.com` 替换为你的实例域名。如果你的实例启用了跨域请求拦截，请将托管该表单的网站添加到 `ALLOWED_ORIGINS` 中。

#### 未登录访客

新项目会创建在访客的账户中，因此访客需要登录。未登录访客如何完成导入取决于导入的发送方式：

* **链接**（`GET /docs?...`）适用于所有实例：访客会被引导至登录页面，登录后导入会继续进行。
* **表单**（`POST /docs`）需要设置 `OVERLEAF_ALLOW_PUBLIC_ACCESS=true` 才能供未登录访客使用。此时提交内容会被保留 10 分钟，直到访客登录，并且仅使用一次。

<Warning>
  默认情况下（未设置 `OVERLEAF_ALLOW_PUBLIC_ACCESS`），未登录访客提交的表单会在 Ayakaleaf Pro 读取之前被重定向到登录页面，提交内容会丢失：登录后，访客会看到 *no snippet, snip\_uri or zip\_uri provided*。请使用链接、要求访客先登录，或启用公开访问，请参阅[页面访问](/zh-CN/on-premises/configuration/overleaf-toolkit/public-access#page-access "mention")。
</Warning>

<Accordion title="可以导入哪些 ZIP 或 TeX 资源？">
  Ayakaleaf Pro 使用 `linked-url-proxy` 微服务（主要用于 [external-url.md](/zh-CN/on-premises/configuration/overleaf-toolkit/external-url "mention")）来获取外部资源。一般来说，任何可通过互联网公开访问的 ZIP 或 TeX 资源都可以导入。出于安全原因，托管在私有网络或内部网络上的资源会被阻止。

  从重新发布的 Ayakaleaf Pro 6.3.0（2026 年 10 月 3 日）开始，你可以通过 `OVERLEAF_LINKED_URL_OUTBOUND_PROXY` 配置一个 HTTP(S) 代理，用于获取外部 ZIP 和 TeX 资源。有关配置和网络访问限制，请参阅[出站代理](/zh-CN/on-premises/configuration/overleaf-toolkit/external-url#outbound-proxy "mention")。
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.