嵌入智慧體

把一個即時的 Buda 智慧體直接呈現給你的使用者——託管 iframe URL 或原生嵌入令牌，全程無需暴露你的 API 金鑰。

讓你的使用者用上真正的智慧體，又不暴露你的金鑰。 你的後端簽發一個短期嵌入憑證，作用域限定在一個會話和一個外部使用者上；前端只用這個憑證與 Buda 通訊。你的 sk_ API 金鑰永遠不離開你的伺服器。

它有兩種形式：

iframe URL（/embed-urls）——一個現成的、由 Buda 託管的對話介面，你只需把它放進 <iframe>。
原生令牌（/embed-sessions）——一個短期令牌，供你自己的介面（移動應用、小程式、擴充套件程式）呼叫嵌入 JSON 端點。

兩者都在服務端用你的 API 金鑰建立。兩者都會過期。

iframe 與原生令牌的對比

	iframe URL（`/embed-urls`）	原生令牌（`/embed-sessions`）
你得到	一個完整的 `embedUrl`，用作 iframe 的 `src`	一個 `token` 加上嵌入 API 的 URL
介面	由 Buda 託管的對話頁面	由你自行構建對話介面
最適合	網站、門戶、後臺管理面板	移動應用、小程式、擴充套件程式
前端呼叫	無（託管頁面已處理）	`/api/v1/embed/chat-sessions/{sessionId}`

切勿直接 iframe /api/v1/embed/...——那些是 JSON API，不是頁面。只有返回的 embedUrl 才適合用作 iframe 的 src。

生成嵌入 URL（iframe）

從你的後端簽發 URL

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-urls \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "customer-123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

響應中包含 embedUrl、sessionId 和 expiresAt：

{
  "embedUrl": "https://buda.im/embed/api-claw/SESSION_ID#token=SHORT_LIVED_TOKEN",
  "sessionId": "SESSION_ID",
  "expiresAt": "2026-05-26T12:00:00.000Z"
}

把它用作 iframe 的 `src`

<iframe
  src="https://buda.im/embed/api-claw/SESSION_ID#token=SHORT_LIVED_TOKEN"
  title="Buda Agent"
  allow="microphone"
  style="width: 400px; height: 600px; border: 0;"
></iframe>

令牌承載在 URL 的 雜湊片段（hash fragment） 中，因此它不會隨首次頁面請求被髮送到伺服器——託管頁面在瀏覽器中讀取它，並僅將其用於嵌入 JSON 呼叫。

生成原生令牌

對於你完全掌控的介面，簽發一個會話並只下發令牌：

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-sessions \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "wechat-openid-oABC123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

只向客戶端返回 token、sessionId 和嵌入 API 的 URL。隨後客戶端用該令牌傳送訊息並輪詢回覆：

# 傳送一條訊息
curl -X POST https://buda.im/api/v1/embed/chat-sessions/SESSION_ID/messages \
  -H "Authorization: Bearer EMBED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my device?", "mode": "chat" }'

# 輪詢智慧體回覆
curl https://buda.im/api/v1/embed/chat-sessions/SESSION_ID \
  -H "Authorization: Bearer EMBED_TOKEN"

令牌有效期與外部使用者

externalUserId（必填）——你自己為終端使用者分配的 ID（客戶 ID、裝置 ID 或微信 openid）。Buda 用它來標記會話；終端使用者無需 Buda 賬戶。
ttlSeconds——令牌的有效時長。最小 60，最大 86400（24 小時），預設 3600（1 小時）。
sessionId——傳入一個已有的會話 ID 以延續對話；省略它則開啟新會話。
mode——提示模式（chat、agent、thinking 或 build-app）。

令牌過期後，從你的後端簽發一個新的。

安全

把 sk_ 金鑰留在服務端。 只有短期嵌入憑證才應到達瀏覽器或裝置。
按使用者限定作用域。 一個嵌入憑證對映到一個 externalUserId 和一個會話——它無法觸及你其他的空間或智慧體。
讓它過期。 使用盡可能短的 ttlSeconds 並按需重新整理，而不是簽發長期令牌。
令牌與會話繫結。 用於其他 sessionId 的令牌會被以 403 拒絕。

嵌入智慧體

iframe 與原生令牌的對比

生成嵌入 URL（iframe）

從你的後端簽發 URL

把它用作 iframe 的 `src`

生成原生令牌

令牌有效期與外部使用者

安全

相關內容

API Claw（爪）

身份認證

REST API

On this page