> ## 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 檔案或壓縮的專案，並在您自己的 Ayakaleaf 執行個體中開啟，類似 Overleaf 的[「Open in Overleaf」API](https://cn.overleaf.com/devs)。

此功能預設為啟用，您只需造訪 `your.overleaf.com/devs` 即可查看詳細頁面與說明。

<Info>
  除非設定了 `OVERLEAF_ALLOW_PUBLIC_ACCESS=true`，否則 `/devs` 頁面需要登入，請參閱[未登入的訪客](/zh-TW/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>

例如，如果您將 LaTeX 檔案託管於 `https://example.com/main.tex`，或將完整專案託管於 `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 檔案或壓縮的專案匯入您自己的 Ayakaleaf Pro 執行個體。當有人開啟該連結時，Ayakaleaf Pro 會以所提供的檔案建立新專案，並在編輯器中開啟。

將連結指向您執行個體的 `/docs` 端點：

| 參數 | 說明 | 範例 |
| - | - | - |
| `snip_uri` | 要匯入的 LaTeX 檔案 URL。也接受單一 ZIP 檔，但專案請使用 `zip_uri`。 | `https://example.com/main.tex` |
| `zip_uri` | 要匯入的壓縮 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 檔案或壓縮的專案以 Base64 data URL 的形式，直接嵌入「Open in Ayakaleaf」連結中。如此一來，您無需將檔案託管於獨立的 URL，即可建立匯入連結。

| 內容 | 參數 | Data URL 格式 |
| - | - | - |
| LaTeX 檔案 | `snip_uri` | `data:application/x-tex;base64,<base64-encoded-tex>` |
| 壓縮的專案 | `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>
```

若要匯入壓縮的專案，請將 `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-TW/on-premises/configuration/overleaf-toolkit/public-access#page-access "mention")。
</Warning>

<Accordion title="我可以匯入哪些 ZIP 或 TeX 資源？">
  Ayakaleaf Pro 使用 `linked-url-proxy` 微服務（主要用於 [external-url.md](/zh-TW/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-TW/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.