Added new endpoints for the gemini live feature

2026-04-02 14:50:03 +08:00
parent 622cf89211
commit cfec9c9bf5
4 changed files with 340 additions and 1 deletions
@@ -63,6 +63,91 @@ Verify if the gateway is online.

 ---

+## 🎙️ Gemini Live Endpoints (Live Practice)
+
+Used by the Live Practice plugin template for real-time voice conversations.
+
+### 4. Generate Live Ephemeral Token
+Exchanges the module API key for a short-lived token the browser can use to open a direct WebSocket to Gemini Live. The server API key is never exposed to the client.
+- **URL**: `http://localhost:8191/api/v1/gemini/live-token`
+- **Method**: `POST`
+- **Headers**: `X-API-Key: <your_key>`
+
+**Request Payload:**
+```json
+{
+  "model": "gemini-2.0-flash-live-001",
+  "system_instruction": "You are a customer service representative named Alex...",
+  "voice_name": "Puck"
+}
+```
+
+**Response:**
+```json
+{
+  "token": "ephemeral-token-value",
+  "expires_at": "2026-04-02T01:00:00Z",
+  "websocket_uri": "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent"
+}
+```
+
+The client connects to the WebSocket URI with `?key={token}` appended.
+
+---
+
+### 5. Score Conversation
+Evaluates a completed conversation transcript against a scorecard using Gemini Flash with structured JSON output.
+- **URL**: `http://localhost:8191/api/v1/gemini/score`
+- **Method**: `POST`
+- **Headers**: `X-API-Key: <your_key>`
+
+**Request Payload:**
+```json
+{
+  "transcript": [
+    { "role": "assistant", "text": "Hi, how can I help you today?" },
+    { "role": "user", "text": "I have a problem with my order." }
+  ],
+  "scorecard": {
+    "criteria": [
+      {
+        "name": "Greeting Quality",
+        "weight": 25,
+        "description": "Did the learner greet the customer warmly?",
+        "good_example": "Hi there! Thanks for reaching out, I'm happy to help.",
+        "poor_example": "What do you want?"
+      }
+    ]
+  },
+  "pass_threshold": 70
+}
+```
+
+**Response:**
+```json
+{
+  "overall_score": 82.5,
+  "passed": true,
+  "criteria_scores": [
+    {
+      "name": "Greeting Quality",
+      "score": 90,
+      "feedback": "The learner greeted warmly and set a positive tone."
+    }
+  ],
+  "positives": [
+    "Maintained a professional tone throughout.",
+    "Actively listened and acknowledged the customer's concern."
+  ],
+  "improvements": [
+    "Could offer a specific resolution timeline earlier.",
+    "Consider using the customer's name for a more personal touch."
+  ]
+}
+```
+
+---
+
 ## 🛠️ Management Endpoints (Internal)

 These endpoints power the Admin Dashboard. They require a Bearer token or Master Key depending on implementation.