純網頁直接整合

在任何頁面加入一個 script 標籤 — 無需建置步驟、無需框架 — 就能從靜態或伺服器端渲染的 HTML 頁面呼叫 API。

本篇適用於純 HTML 頁面 — 伺服器端渲染、靜態頁面，或是隨手加進任何網站的 <script> 標籤，無需建置步驟，也無需框架。改用 React？請見 React SPA 整合。不確定哪一篇指南適合您的技術棧？請見選擇您的整合路徑。

從零到完成最快的示範

一個 script 標籤加上幾行 JavaScript — 最快看到真正呼叫成功的方式。您需要先準備一把真正的 x-api-key（見下方說明它從哪裡來 — 這跟取得您的 API 金鑰拿到的 client_id/client_secret 是不同的憑證）。

1. 加入 script 標籤

<script src="https://js.quravin.com/v1.js"></script>

2. 建立客戶端並呼叫 ai.run()

<button id="go">Translate</button>
<div id="out"></div>

<script>
  const ai = new Quravin.Quravin({
    endpoint: "https://api.quravin.com",
    apiKey:   "YOUR_API_KEY",
  });

  document.getElementById("go").onclick = async () => {
    const out = await ai.run({
      pipeline: "translate-string",
      inputs: { text: "Hello", target_language: "de" },
    });
    document.getElementById("out").textContent = out.translation;
  };
</script>

點擊按鈕 — out 會得到 { translation: "Hallo" }。這就是完整的一次來回：提交、輪詢、完成。 endpoint 就是您的 API 基礎 URL，不需要加任何路徑 — 網域後面不要再附加任何內容。

要去哪裡拿 API 金鑰？

靜態的 x-api-key 是與 client_id/client_secret 組合不同的另一種自助式憑證 — 在 Console 中開啟您 app 的詳細頁面，點擊 Regenerate API Key 即可。詳見取得您的 API 金鑰的「關於靜態的 x-api-key？」章節。

這段範例只適合快速本機測試 — 絕對不要把正式的 apiKey 放進瀏覽器程式碼中。請繼續閱讀下一節，了解安全、可用於正式環境的做法。

正式環境：請改用 session token

絕對不要把靜態的 x-api-key 放進使用者瀏覽器會下載到的頁面。任何人都能從頁面原始碼讀到它，並冒充您的身分使用。正式環境安全的做法是：由您自己的 backend 發行一把短效、每位使用者一個的 session JWT 交給頁面 — 頁面永遠不會看到活得比單次造訪更久的機密。

建置這個 backend endpoint 的方式無論用什麼語言撰寫都一樣 — Node.js 伺服器整合展示了一個完整可運作的範例（它發出的 POST /auth/token 請求是單純的 HTTP，所以任何 backend 語言的做法都相同）。有了 token endpoint 之後，瀏覽器端的程式碼會長這樣：

<input id="text" />
<button id="go">Translate</button>
<span id="result"></span>

<script src="https://js.quravin.com/v1.js"></script>
<script>
  const fetchToken = async () => {
    const r = await fetch("/ai-token", { credentials: "include" });
    if (!r.ok) throw new Error("Token fetch failed");
    return (await r.json()).token;
  };

  const ai = new Quravin.Quravin({
    endpoint: "https://api.quravin.com",
    sessionToken: await fetchToken(),
    onTokenExpired: fetchToken,   // API 回傳 401 時自動更新
  });

  document.getElementById("go").onclick = async () => {
    const out = await ai.run({
      pipeline: "translate-string",
      inputs: { text: document.getElementById("text").value, target_language: "de" },
    });
    document.getElementById("result").textContent = out.translation;
  };
</script>

fetch("/ai-token", { credentials: "include" }) 是對您自己 backend 的同源呼叫 — 不涉及 CORS，只是您平常使用的 cookie-based session。完整的 apiKey 與 sessionToken 比較請見選擇您的認證模式，每個工具的輸入與各呼叫路徑可能回傳的錯誤請見工具參考手冊。