{ "openapi": "3.0.3", "info": { "title": "Kaleo API", "version": "2026-10-08", "description": "Kaleo AI 提供一個網路 API，用於控制您的串流會議、檢索觀眾分析，並監控 Kaleo Connect 裝置。您可以根據需要使用我們的 API 整合到您的自訂 AVL 控制和工作流程中。\n\n開始使用，請依照以下說明取得 API 金鑰、查找您的教會 ID，並驗證您的請求。\n\n## 取得 API 金鑰\n\n1. 前往您的儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面。\n2. 輸入名稱並選擇 **建立 API 金鑰**。\n3. 複製金鑰並妥善保存。完整金鑰僅顯示一次。\n\n每個金鑰僅適用於一個教會。其建立者必須持續為該教會成員。\n\n## 查找您的教會 ID\n\n從您的儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製 **教會 ID**。在您的 API 請求中使用此 ID 作為 `churchId`。\n\n## 驗證\n\n每次請求時，請準確使用從 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製的金鑰：\n\n```text\nAuthorization: Bearer YOUR_API_KEY\n```\n\n在 API 遊樂場中，只需輸入您複製的金鑰。Bearer 會自動添加。" }, "servers": [ { "url": "https://babel.withkaleo.com", "description": "正式環境 API" } ], "tags": [ { "name": "Languages", "description": "支援的講者和翻譯語言。", "x-displayName": "語言" }, { "name": "Devices", "description": "可透過 API 監控和遠端控制的 Kaleo Connect 裝置。", "x-displayName": "裝置" }, { "name": "Streaming", "description": "**注意：啟動串流端點僅能用於從 Kaleo Connect 裝置啟動串流。** 此端點無法用於從網頁瀏覽器啟動串流。其他串流端點可控制瀏覽器和 Kaleo Connect 裝置。", "x-displayName": "串流" }, { "name": "Sessions", "description": "會議歷史與觀眾分析。", "x-displayName": "會議" } ], "security": [ { "ApiKeyBearer": [] } ], "paths": { "/v1/church/{churchId}/devices": { "get": { "operationId": "listDevices", "summary": "列出裝置", "tags": [ "Devices" ], "description": "列出 Kaleo Connect 裝置及其功能準備狀態。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Devices" }, "example": { "devices": [ { "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac", "status": "online", "capabilities": [ { "capability": "audio-source", "status": "ready" }, { "capability": "audio-output", "status": "ready" }, { "capability": "propresenter", "status": "unavailable" } ], "lastSeenAt": null } ] } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List devices" } }, "/v1/church/{churchId}/devices/{deviceId}": { "get": { "operationId": "getDevice", "summary": "取得裝置", "tags": [ "Devices" ], "description": "讀取單一 Kaleo Connect 裝置及其功能準備狀態。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "來自 `GET /devices` 的裝置 ID。" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetails" }, "example": { "device": { "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac", "status": "online", "capabilities": [ { "capability": "audio-source", "status": "ready" }, { "capability": "audio-output", "status": "ready" }, { "capability": "propresenter", "status": "unavailable" } ], "lastSeenAt": null } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "此教會中不存在該裝置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICE_NOT_FOUND" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "DEVICES_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get device" } }, "/v1/church/{churchId}/streaming": { "get": { "operationId": "getStreaming", "summary": "取得串流狀態", "tags": [ "Streaming" ], "description": "讀取目前會議及共享教會設定。所有欄位皆存在，包括閒置時。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get streaming status" } }, "/v1/church/{churchId}/streaming/start": { "post": { "operationId": "startStreaming", "summary": "開始串流", "tags": [ "Streaming" ], "description": "使用儲存的設定在 Kaleo Connect 裝置上開始串流。可選的主體可選擇 `deviceId` 並覆寫此會議的設定。若未提供 `deviceId`，當有多個支援音訊的裝置時，Kaleo 將選擇儀表板中「整合」下的 [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) 頁面所設定的預設音訊來源；若只有一個可用音訊來源裝置，則使用該裝置。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "格式錯誤的 JSON、不支援的欄位或無效值。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "403": { "description": "方案、語言或使用限制阻止此啟動。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "PLAN_LIMIT" } } } }, "409": { "description": "有活動會議衝突、缺少音訊來源或預設選擇，或選擇的裝置尚未準備好。請先讀取串流狀態和裝置準備狀態；在儀表板中「整合」下的 [Kaleo Connect](https://app.withkaleo.com/to/integrations/connect) 頁面選擇預設，或在需要時提供 `deviceId`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "ACTIVE_SESSION" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartStreaming" }, "examples": { "defaultAudioSource": { "summary": "使用預設音訊來源", "value": {} }, "explicitDevice": { "summary": "為此會議選擇裝置", "value": { "deviceId": "00000000-0000-4000-8000-000000000002" } } } } }, "description": "省略主體或傳送 `{}` 以使用預設音訊來源和儲存設定。傳送 `deviceId` 以為此會議選擇其他裝置。" }, "x-kaleo-anchor": "Start streaming" } }, "/v1/church/{churchId}/streaming/stop": { "post": { "operationId": "stopStreaming", "summary": "停止串流", "tags": [ "Streaming" ], "description": "停止目前的串流會議。不需要請求主體。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": false, "sessionId": null, "startedAt": null, "deadlineAt": null, "speakerLanguage": null, "targetLanguages": [], "voice": "male", "visible": true, "publisher": null, "phase": "idle", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Stop streaming" } }, "/v1/church/{churchId}/streaming/voice": { "patch": { "operationId": "changeVoice", "summary": "更改翻譯語音", "tags": [ "Streaming" ], "description": "在閒置或串流時更改翻譯語音。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "female", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "格式錯誤的 JSON、不支援的欄位或無效值。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "串流已變更或無法確認指令。請先讀取目前串流狀態再發送其他指令。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_CHANGED" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVoice" }, "example": { "voice": "female" } } } }, "x-kaleo-anchor": "Change translation voice" } }, "/v1/church/{churchId}/streaming/visibility": { "patch": { "operationId": "changeVisibility", "summary": "更改可見性", "tags": [ "Streaming" ], "description": "在閒置或串流時顯示或隱藏字幕。隱藏字幕不會停止會議。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": false, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "格式錯誤的 JSON、不支援的欄位或無效值。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeVisibility" }, "example": { "visible": false } } } }, "x-kaleo-anchor": "Change visibility" } }, "/v1/church/{churchId}/streaming/captions/clear": { "post": { "operationId": "clearCaptions", "summary": "清除字幕", "tags": [ "Streaming" ], "description": "清除目前的字幕串流。不需要請求主體。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Clear captions" } }, "/v1/church/{churchId}/streaming/deadline": { "patch": { "operationId": "changeDeadline", "summary": "更改自動停止截止時間", "tags": [ "Streaming" ], "description": "設定活動會議的自動停止時間。回傳更新後的串流狀態。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "格式錯誤的 JSON、不支援的欄位或無效值。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`STREAM_OFFLINE` 當閒置時；`INVALID_DEADLINE` 當截止時間超出允許範圍。請先讀取目前串流狀態再發送其他指令。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeDeadline" }, "example": { "deadlineAt": "2026-10-08T16:00:00Z" } } } }, "x-kaleo-anchor": "Change auto-stop deadline" } }, "/v1/church/{churchId}/sessions": { "get": { "operationId": "listSessions", "summary": "列出會議", "tags": [ "Sessions" ], "description": "列出會議，最新的在前，包含觀眾分析。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "頁碼，從 1 開始。超過最後一頁的值會回傳最後一頁。" }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 14 }, "description": "每頁會議數。超過 100 的值會使用 100。" }, { "name": "startedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "包含在此時間或之後開始的會議。請包含 Z 或時區偏移。" }, { "name": "startedBefore", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "包含在此時間或之前開始的會議。請包含 Z 或時區偏移。必須在 `startedAfter` 之後或相同時間。" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPage" }, "example": { "sessions": [ { "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-04T14:00:00.000Z", "endedAt": "2026-10-04T15:00:00.000Z", "duration": 3600, "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "transcriptAvailable": true, "publicSharingEnabled": false, "analytics": { "sessionId": "00000000-0000-4000-8000-000000000001", "status": "finalized", "viewers": 12, "viewerLanguages": { "en": 8, "fr-FR": 6 } } } ], "total": 1, "page": 1, "pageSize": 14 } } }, "headers": { "Cache-Control": { "description": "讀取回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "無效的正整數分頁或無效/反向的時間戳範圍。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_HISTORY_RANGE" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是教會成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "歷史或驗證服務不可用。非空歷史結果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List sessions" } }, "/v1/church/{churchId}/sessions/{sessionId}": { "get": { "operationId": "getSession", "summary": "取得會議", "tags": [ "Sessions" ], "description": "讀取單一會議及其觀眾分析。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "來自 `GET /sessions` 的會議 ID。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetails" }, "example": { "session": { "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-04T14:00:00.000Z", "endedAt": "2026-10-04T15:00:00.000Z", "duration": 3600, "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "transcriptAvailable": true, "publicSharingEnabled": false, "analytics": { "sessionId": "00000000-0000-4000-8000-000000000001", "status": "finalized", "viewers": 12, "viewerLanguages": { "en": 8, "fr-FR": 6 } } } } } }, "headers": { "Cache-Control": { "description": "讀取回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是教會成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "會議遺失、已移除、無效 ID，或屬於不同擁有者。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_NOT_FOUND" } } } }, "503": { "description": "歷史或驗證服務不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "SESSION_HISTORY_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get session" } }, "/v1/church/{churchId}/languages/speaker": { "get": { "operationId": "listSpeakerLanguages", "summary": "列出講者語言", "tags": [ "Languages" ], "description": "列出支援的講者語言。請在 `speakerLanguage` 中使用這些代碼。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "驗證服務暫時不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List speaker languages" } }, "/v1/church/{churchId}/languages/target": { "get": { "operationId": "listTargetLanguages", "summary": "列出目標語言", "tags": [ "Languages" ], "description": "列出支援的翻譯語言。請在 `targetLanguages` 中使用這些代碼。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "example": { "languages": [ { "code": "en", "name": "English", "nativeName": "English", "emoji": "🌎" } ] } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "503": { "description": "驗證服務暫時不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "List target languages" } }, "/v1/church/{churchId}/languages/{code}": { "get": { "operationId": "getLanguage", "summary": "取得語言", "tags": [ "Languages" ], "description": "讀取一個支援語言代碼的名稱與表情符號。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "精確語言代碼，例如 `en` 或 `zh-Hans`。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetails" }, "example": { "language": { "code": "fr", "name": "French (General)", "nativeName": "Français", "emoji": "🇫🇷" } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "404": { "description": "不支援的語言代碼。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "LANGUAGE_NOT_FOUND" } } } }, "503": { "description": "驗證服務暫時不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "AUTHENTICATION_UNAVAILABLE" } } } } }, "x-kaleo-anchor": "Get language" } }, "/v1/church/{churchId}/streaming/deadline/adjust": { "post": { "operationId": "adjustDeadline", "summary": "調整自動停止時間", "tags": [ "Streaming" ], "description": "增加或減少自動停止時間。閒置時，變更下一次手動啟動的持續時間。串流時，變更目前的截止時間。每個請求會套用獨立調整。", "parameters": [ { "name": "churchId", "in": "path", "required": true, "description": "您的教會 ID。從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingStatus" }, "example": { "streaming": true, "sessionId": "00000000-0000-4000-8000-000000000001", "startedAt": "2026-10-08T14:00:00.000Z", "deadlineAt": "2026-10-08T16:00:00.000Z", "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "voice": "male", "visible": true, "publisher": { "kind": "connect", "id": "00000000-0000-4000-8000-000000000002", "name": "Sanctuary Mac" }, "phase": "streaming", "streamSettings": { "revision": 4, "settings": { "speakerLanguage": "en", "targetLanguages": [ "fr-FR" ], "duration": 3600 } } } } }, "headers": { "Cache-Control": { "description": "回應不會被快取。", "schema": { "type": "string", "enum": [ "no-store" ] } } } }, "400": { "description": "格式錯誤的 JSON、不支援的欄位或無效值。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_REQUEST" } } } }, "401": { "description": "缺少或無效的 API 金鑰，包括過期、撤銷、錯誤教會，或建立者不再是成員。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "API_KEY_INVALID" } } } }, "409": { "description": "`INVALID_DEADLINE` 當直播截止時間超出允許範圍；`DEADLINE_NOT_SET` 當會議無截止時間。`SETTINGS_CHANGED` 或 `SESSION_ACTIVE` 當閒置設定或入場同時變更。請先讀取目前串流狀態再發送其他指令。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "INVALID_DEADLINE" } } } }, "503": { "description": "暫時的服務或驗證失敗。重整狀態後再嘗試控制請求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "CONTROL_UNAVAILABLE" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustDeadline" }, "example": { "deltaSeconds": 120 } } } }, "x-kaleo-anchor": "Adjust auto-stop time" } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "請準確輸入從儀表板中「整合」下的 [API](https://app.withkaleo.com/to/integrations/api) 頁面複製的 API 金鑰。Bearer 會自動添加。此金鑰適用於一個教會，且建立者必須持續為成員。" } }, "schemas": { "Device": { "type": "object", "properties": { "id": { "type": "string", "description": "裝置 ID。請在請求中以 `deviceId` 傳遞此值。" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "offline", "online", "maintenance" ], "description": "連線狀態。90 秒無聯繫即離線；維護中表示暫時無法使用。" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCapability" }, "description": "此裝置各功能的準備狀態。" }, "lastSeenAt": { "type": "string", "format": "date-time", "nullable": true, "description": "最後與 Kaleo 聯繫時間；若未知則為 `null`。" } }, "required": [ "id", "name", "status", "capabilities", "lastSeenAt" ], "additionalProperties": false }, "DeviceCapability": { "type": "object", "properties": { "capability": { "type": "string", "enum": [ "audio-source", "audio-output", "propresenter" ], "description": "本地功能：音訊擷取、翻譯語音播放或 ProPresenter 投影片輸入。" }, "status": { "type": "string", "enum": [ "ready", "unavailable", "offline" ], "description": "此功能是否準備好使用。" } }, "required": [ "capability", "status" ], "additionalProperties": false }, "Devices": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } }, "required": [ "devices" ], "additionalProperties": false }, "DeviceDetails": { "type": "object", "properties": { "device": { "$ref": "#/components/schemas/Device" } }, "required": [ "device" ], "additionalProperties": false }, "ProPresenterSelection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "default" ], "description": "使用教會的預設 ProPresenter 裝置。" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ], "description": "此會議不使用 ProPresenter。" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "device" ], "description": "使用由 `deviceId` 指定的裝置。" }, "deviceId": { "type": "string", "description": "ProPresenter 來源的裝置 ID，來自 `GET /devices`。可能與音訊來源不同。" } }, "required": [ "mode", "deviceId" ], "additionalProperties": false } ], "description": "為此會議選擇 ProPresenter 來源。請在 Connect 中設定其連線。" }, "StartStreaming": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "可選的音訊來源裝置 ID，來自 `GET /devices`。此設定會覆寫教會預設，僅限此會議使用。若省略，則使用儲存的預設音訊來源或唯一支援音訊來源的配對裝置；若有多個裝置且無預設，則需選擇。所選裝置必須仍處於準備狀態。" }, "overrides": { "type": "object", "properties": { "speakerLanguage": { "type": "string", "description": "來自 `GET /languages/speaker` 的代碼。多語言模式請使用 `\"mul\"`。" }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "來自 `GET /languages/target` 的代碼。使用 `[\"ALL\"]` 表示所有支援目標語言，且在您的方案限制內。" }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "自動停止時間，單位為秒。" }, "proPresenter": { "$ref": "#/components/schemas/ProPresenterSelection" } }, "required": [], "additionalProperties": false, "description": "僅限此會議的設定。省略欄位將使用儲存的預設值。" } }, "required": [], "additionalProperties": false }, "ChangeVoice": { "type": "object", "properties": { "voice": { "type": "string", "enum": [ "male", "female" ], "description": "翻譯語音。可在閒置或串流時更改。" } }, "required": [ "voice" ], "additionalProperties": false }, "ChangeVisibility": { "type": "object", "properties": { "visible": { "type": "boolean", "description": "`true` 顯示字幕；`false` 隱藏字幕，但串流持續。" } }, "required": [ "visible" ], "additionalProperties": false }, "ChangeDeadline": { "type": "object", "properties": { "deadlineAt": { "type": "string", "format": "date-time", "description": "未來的自動停止時間，需包含 Z 或時區偏移。不得晚於 `startedAt` 後六小時。" } }, "required": [ "deadlineAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" } }, "required": [ "success", "error" ] }, "Analytics": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "pending", "finalized" ], "description": "`live`：臨時計數；`pending`：等待最終計數；`finalized`：已儲存計數。" }, "viewers": { "type": "integer", "minimum": 0, "nullable": true, "description": "會議的唯一觀眾身份，不是目前觀眾。若無法取得為 `null`；0 表示無觀眾。" }, "viewerLanguages": { "type": "object", "nullable": true, "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "依語言代碼的觀眾分析。觀眾可能出現在多個語言中。若無法取得為 `null`。" } }, "required": [ "sessionId", "status", "viewers", "viewerLanguages" ] }, "HistorySession": { "type": "object", "properties": { "sessionId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "會議結束時間；若未完成或無法取得為 `null`。" }, "duration": { "type": "integer", "nullable": true, "description": "記錄的會議長度（秒）；若未完成或無法取得為 `null`。" }, "speakerLanguage": { "type": "string", "nullable": true, "description": "講者語言代碼；若未記錄為 `null`。" }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "記錄的翻譯語言代碼，或為 `[\"ALL\"]`。" }, "transcriptAvailable": { "type": "boolean", "description": "當儲存的逐字稿準備好時為 `true`。不代表公開存取或下載連結。" }, "publicSharingEnabled": { "type": "boolean", "description": "當完成會議啟用公開分享時為 `true`。" }, "analytics": { "$ref": "#/components/schemas/Analytics" } }, "required": [ "sessionId", "startedAt", "endedAt", "duration", "speakerLanguage", "targetLanguages", "transcriptAvailable", "publicSharingEnabled", "analytics" ] }, "HistoryPage": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/HistorySession" } }, "total": { "type": "integer", "minimum": 0, "description": "符合篩選條件的會議總數，跨所有頁面。" }, "page": { "type": "integer", "minimum": 1, "description": "回傳的頁碼；可能低於請求的頁碼。" }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "每頁最大會議數，最高為 100。" } }, "required": [ "sessions", "total", "page", "pageSize" ] }, "SessionDetails": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/HistorySession" } }, "required": [ "session" ] }, "Language": { "type": "object", "properties": { "code": { "type": "string", "description": "請在語言欄位中使用此精確代碼。" }, "name": { "type": "string", "description": "英文顯示名稱。" }, "nativeName": { "type": "string", "description": "該語言的本地名稱；若無則為英文名稱。" }, "emoji": { "type": "string", "description": "此語言的顯示表情符號。" } }, "required": [ "code", "name", "nativeName", "emoji" ], "additionalProperties": false }, "Languages": { "type": "object", "properties": { "languages": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } }, "required": [ "languages" ], "additionalProperties": false }, "LanguageDetails": { "type": "object", "properties": { "language": { "$ref": "#/components/schemas/Language" } }, "required": [ "language" ], "additionalProperties": false }, "StreamingStatus": { "type": "object", "properties": { "streaming": { "type": "boolean", "description": "`true` 表示活動會議中，包括啟動、重新連線和關閉。無法確認音訊是否到達。" }, "sessionId": { "type": "string", "nullable": true, "description": "目前會議 ID；閒置時為 `null`。" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "目前會議開始時間；閒置時為 `null`。" }, "deadlineAt": { "type": "string", "format": "date-time", "nullable": true, "description": "自動停止時間；閒置時或無截止時間時為 `null`。" }, "speakerLanguage": { "type": "string", "nullable": true, "description": "目前講者語言代碼；閒置時為 `null`。" }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "目前翻譯語言代碼；閒置時為空。" }, "voice": { "type": "string", "enum": [ "male", "female", null ], "nullable": false, "description": "翻譯語音，包括閒置時。" }, "visible": { "type": "boolean", "description": "`true` 顯示字幕；`false` 隱藏字幕。閒置時亦適用。" }, "publisher": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "connect" ] }, "id": { "type": "string", "description": "當 `kind` 為 `connect` 時為裝置 ID；當 `kind` 為 `browser` 時為瀏覽器發布者 ID。" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ], "additionalProperties": false, "nullable": true, "description": "發送音訊的 Kaleo Connect 裝置或瀏覽器；閒置時為 `null`。" }, "phase": { "type": "string", "enum": [ "idle", "starting", "streaming", "reconnecting", "ending" ], "description": "會議階段；閒置表示無活動會議。" }, "streamSettings": { "type": "object", "description": "教會預設的下一次手動啟動設定。活動會議的覆寫不會更改這些值。", "required": [ "revision", "settings" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "當這些預設變更時增加。" }, "settings": { "type": "object", "required": [ "speakerLanguage", "targetLanguages", "duration" ], "properties": { "speakerLanguage": { "type": "string", "description": "預設講者語言代碼。" }, "targetLanguages": { "type": "array", "items": { "type": "string" }, "description": "預設翻譯語言代碼；`[\"ALL\"]` 表示選擇所有支援目標。" }, "duration": { "type": "integer", "minimum": 60, "maximum": 21600, "description": "自動停止時間，單位為秒。" } } } } } }, "required": [ "streaming", "phase", "sessionId", "startedAt", "deadlineAt", "speakerLanguage", "targetLanguages", "voice", "visible", "publisher", "streamSettings" ], "additionalProperties": false, "description": "目前會議及共享教會設定。所有欄位皆存在，包括閒置時。" }, "AdjustDeadline": { "type": "object", "additionalProperties": false, "required": [ "deltaSeconds" ], "properties": { "deltaSeconds": { "type": "integer", "minimum": -21600, "maximum": 21600, "description": "要加到閒置持續時間或目前截止時間的秒數；負值表示減少。不可為 0。閒置持續時間：60–21600 秒。直播截止時間：未來，且在 `startedAt` 後六小時內。", "not": { "enum": [ 0 ] } } } } } } }