{ "success": true, "data": { "openapi": "3.1.0", "info": { "title": "OmniModal Public Developer API", "version": "1.0.0", "description": "Public-facing onboarding and core integration routes for OmniModal.\n\nStable integration baseline:\n- Base URL: https://omnimodal.shenliu.cc/api\n- Auth header: x-omnimodal-api-key\n- Realtime production path: pcm16 / 16000 / mono\n- webm_opus remains experimental and should not be the default commercial path\n\nError envelope:\n- { \"success\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }" }, "servers": [ { "url": "https://omnimodal.shenliu.cc/api" } ], "components": { "securitySchemes": { "OmniModalApiKey": { "type": "apiKey", "in": "header", "name": "x-omnimodal-api-key" } }, "schemas": { "StandardEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object" } } }, "ErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "Tenant": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tenantName": { "type": "string" }, "editionType": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "tenantId", "tenantName", "editionType", "status" ] }, "TenantApiKey": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "tenantId": { "type": "string" }, "label": { "type": "string" }, "keyPreview": { "type": "string" }, "roleCode": { "type": "string" }, "status": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } }, "required": [ "apiKeyId", "tenantId", "label", "keyPreview", "roleCode", "status", "secret" ] }, "TenantSignupRequest": { "type": "object", "properties": { "companyName": { "type": "string" }, "contactName": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "desiredPlan": { "type": "string" }, "scenario": { "type": "string" }, "message": { "type": "string" } }, "required": [ "companyName", "contactName", "phone", "email", "desiredPlan", "scenario" ] }, "TenantSignupResponse": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/Tenant" }, "apiKey": { "$ref": "#/components/schemas/TenantApiKey" }, "onboarding": { "type": "object", "properties": { "apiBaseUrl": { "type": "string" }, "authHeader": { "type": "string" }, "role": { "type": "string" } }, "required": [ "apiBaseUrl", "authHeader", "role" ] }, "initialization": { "type": "object", "properties": { "billingProfileCreated": { "type": "boolean" }, "accessPolicyCreated": { "type": "boolean" }, "storageConfigCreated": { "type": "boolean" }, "welcomeEntryCreated": { "type": "boolean" } }, "required": [ "billingProfileCreated", "accessPolicyCreated", "storageConfigCreated", "welcomeEntryCreated" ] } }, "required": [ "tenant", "apiKey", "onboarding", "initialization" ] }, "MultimodalEntryRequest": { "type": "object", "properties": { "tenantId": { "type": "string" }, "scene": { "type": "string" }, "intent": { "type": "string" }, "mode": { "type": "string", "enum": [ "voice", "text", "image", "file", "mixed" ] }, "text": { "type": "string" }, "businessContext": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "tenantId", "scene", "mode" ] }, "MultimodalEntryResponse": { "type": "object", "properties": { "entryId": { "type": "string" }, "tenantId": { "type": "string" }, "routingStatus": { "type": "string" }, "scene": { "type": "string" }, "mode": { "type": "string" }, "skillCode": { "type": [ "string", "null" ] }, "linkedIngestionIds": { "type": "array", "items": { "type": "string" } }, "linkedTaskIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "entryId", "tenantId", "routingStatus", "scene", "mode", "linkedIngestionIds", "linkedTaskIds", "createdAt" ] }, "IngestionRequest": { "type": "object", "properties": { "tenantId": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileUri": { "type": "string" }, "documentType": { "type": "string" } }, "required": [ "tenantId", "fileName", "fileUri", "documentType" ] }, "IngestionAcceptedResponse": { "type": "object", "properties": { "ingestionId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "ingestionId", "status" ] }, "TaskRequest": { "type": "object", "properties": { "tenantId": { "type": "string" }, "ingestionId": { "type": "string" }, "taskType": { "type": "string" }, "providerCode": { "type": "string" }, "sourcePayload": { "type": "object", "additionalProperties": true, "properties": { "executionPreferences": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "route_order", "balanced", "latency_first", "cost_first", "commercial_first", "reliability_first" ] }, "preferredProviderCodes": { "type": "array", "items": { "type": "string" } }, "blockedProviderCodes": { "type": "array", "items": { "type": "string" } }, "disableFallbackProviderCodes": { "type": "array", "items": { "type": "string" } } } } } } }, "required": [ "tenantId", "ingestionId", "taskType", "providerCode" ] }, "TaskAcceptedResponse": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "taskId", "status" ] }, "TaskDetailResponse": { "type": "object", "properties": { "taskId": { "type": "string" }, "tenantId": { "type": "string" }, "ingestionId": { "type": "string" }, "taskType": { "type": "string" }, "providerCode": { "type": "string" }, "status": { "type": "string" }, "retryCount": { "type": [ "integer", "null" ] }, "executionCursor": { "type": [ "integer", "null" ] }, "nextRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastErrorMessage": { "type": [ "string", "null" ] }, "deadLetteredAt": { "type": [ "string", "null" ], "format": "date-time" }, "deadLetterReason": { "type": [ "string", "null" ] }, "operatorNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resultId": { "type": [ "string", "null" ] } }, "required": [ "taskId", "tenantId", "ingestionId", "taskType", "providerCode", "status", "createdAt", "updatedAt", "resultId" ] }, "TaskResultResponse": { "type": "object", "properties": { "resultId": { "type": "string" }, "taskId": { "type": "string" }, "tenantId": { "type": "string" }, "schemaType": { "type": "string" }, "schemaVersion": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "rawPayloadRef": { "type": [ "string", "null" ] }, "confidenceLevel": { "type": [ "string", "null" ] }, "sourceContext": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "resultId", "taskId", "tenantId", "schemaType", "schemaVersion", "payload", "createdAt" ] }, "RealtimeSessionRequest": { "type": "object", "properties": { "tenantId": { "type": "string" }, "scene": { "type": "string" }, "intent": { "type": "string" }, "mode": { "type": "string", "enum": [ "voice" ] }, "preflight": { "type": "boolean" }, "providerCode": { "type": "string" }, "audioConfig": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "pcm16", "opus", "webm_opus" ] }, "sampleRate": { "type": "integer" }, "channelCount": { "type": "integer" } }, "required": [ "codec", "sampleRate", "channelCount" ] }, "tuning": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "short_query", "balanced", "rapid_speech", "dictation", "noisy_environment" ] }, "turnDetectionType": { "type": "string" }, "vadThreshold": { "type": "number", "minimum": -1, "maximum": 1 }, "silenceDurationMs": { "type": "integer", "minimum": 100, "maximum": 5000 }, "commitTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 } } }, "businessContext": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "tenantId", "scene", "mode", "audioConfig" ] }, "RealtimeSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string" }, "tenantId": { "type": "string" }, "scene": { "type": "string" }, "intent": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "status": { "type": "string" }, "audioConfig": { "type": "object", "additionalProperties": true }, "businessContext": { "type": "object", "additionalProperties": { "type": "string" } }, "asrRouting": { "type": "object", "properties": { "providerCode": { "type": [ "string", "null" ] }, "adapter": { "type": "string" }, "status": { "type": "string" }, "fallbackDisabled": { "type": "boolean" }, "upstreamConnectivity": { "type": "string" }, "preflightLatencyMs": { "type": "number" }, "checkedAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "codecSupport": { "type": "object", "properties": { "requestedCodec": { "type": "string" }, "accepted": { "type": "boolean" }, "status": { "type": "string" }, "productionReady": { "type": "boolean" }, "experimental": { "type": "boolean" }, "recommendedCodec": { "type": "string" }, "requiresClientPcm16": { "type": "boolean" }, "serverTranscodeAvailable": { "type": "boolean" }, "message": { "type": "string" }, "errorCode": { "type": [ "string", "null" ] } }, "required": [ "requestedCodec", "accepted", "status", "productionReady", "experimental", "recommendedCodec", "requiresClientPcm16", "serverTranscodeAvailable", "message", "errorCode" ] } }, "required": [ "providerCode", "adapter", "status", "fallbackDisabled" ] }, "runtimeConfig": { "type": "object", "properties": { "adapter": { "type": "string" }, "profile": { "type": "string" }, "turnDetectionType": { "type": "string" }, "vadThreshold": { "type": "number" }, "silenceDurationMs": { "type": "integer" }, "commitTimeoutMs": { "type": "integer" }, "sessionTuningApplied": { "type": "boolean" }, "codecSupport": { "type": "object", "properties": { "requestedCodec": { "type": "string" }, "accepted": { "type": "boolean" }, "status": { "type": "string" }, "productionReady": { "type": "boolean" }, "experimental": { "type": "boolean" }, "recommendedCodec": { "type": "string" }, "requiresClientPcm16": { "type": "boolean" }, "serverTranscodeAvailable": { "type": "boolean" }, "message": { "type": "string" }, "errorCode": { "type": [ "string", "null" ] } }, "required": [ "requestedCodec", "accepted", "status", "productionReady", "experimental", "recommendedCodec", "requiresClientPcm16", "serverTranscodeAvailable", "message", "errorCode" ] } } }, "wsUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" } }, "required": [ "sessionId", "tenantId", "scene", "mode", "status", "audioConfig", "businessContext", "asrRouting", "runtimeConfig", "wsUrl", "expiresAt", "startedAt" ] }, "LexiconTerm": { "type": "object", "properties": { "canonical": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "weight": { "type": "number" }, "source": { "type": "string" }, "status": { "type": "string" } }, "required": [ "canonical", "aliases", "category", "weight", "source", "status" ] }, "TranscriptFeedbackRequest": { "type": "object", "properties": { "sessionId": { "type": "string" }, "utteranceId": { "type": "string" }, "industryCode": { "type": "string" }, "sourceSystem": { "type": "string" }, "originalText": { "type": "string" }, "correctedText": { "type": "string" }, "note": { "type": "string" }, "status": { "type": "string" } }, "required": [ "originalText", "correctedText" ] } } }, "paths": { "/health": { "get": { "summary": "Health check", "security": [], "parameters": [ { "name": "deep", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, performs an upstream realtime ASR connectivity probe." } ], "responses": { "200": { "description": "Service is healthy or degraded but still serving requests" }, "503": { "description": "Service readiness failed" } } } }, "/v1/public/self-serve/signup": { "post": { "summary": "Create trial tenant and issue first integration key", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSignupRequest" }, "example": { "companyName": "深流科技", "contactName": "张三", "phone": "13800000000", "email": "ops@example.com", "desiredPlan": "starter", "scenario": "ziin integration test", "message": "public api test" } } } }, "responses": { "201": { "description": "Tenant and API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "tenant": { "tenantId": "tenant_tenant_fb38cc", "tenantName": "深流科技", "editionType": "self_serve", "status": "active", "createdAt": "2026-04-17T13:30:00.000Z", "updatedAt": "2026-04-17T13:30:00.000Z" }, "apiKey": { "apiKeyId": "apikey_4c7b9b5e3f2d", "tenantId": "tenant_tenant_fb38cc", "label": "self-serve-integration-key", "keyPreview": "omni_live_tenant_tenant_fb38cc_...", "roleCode": "integration_system", "status": "active", "lastUsedAt": null, "createdAt": "2026-04-17T13:30:00.000Z", "updatedAt": "2026-04-17T13:30:00.000Z", "secret": "omni_live_tenant_tenant_fb38cc_integration_system_xxxxxxxx" }, "onboarding": { "apiBaseUrl": "/api", "authHeader": "x-omnimodal-api-key", "role": "integration_system" }, "initialization": { "billingProfileCreated": true, "accessPolicyCreated": true, "storageConfigCreated": true, "welcomeEntryCreated": true } } } } } }, "400": { "description": "Invalid signup payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/public/self-serve/admin-claim": { "post": { "summary": "Claim tenant admin key for self-serve tenant", "security": [], "requestBody": { "required": true, "content": { "application/json": { "example": { "tenantId": "tenant_tenant_fb38cc", "email": "ops@example.com", "phone": "13800000000" } } } }, "responses": { "201": { "description": "Tenant admin API key issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "tenant": { "tenantId": "tenant_tenant_fb38cc", "tenantName": "深流科技", "editionType": "self_serve", "status": "active" }, "apiKey": { "apiKeyId": "apikey_admin_xxxx", "tenantId": "tenant_tenant_fb38cc", "label": "self-serve-tenant-admin-key", "keyPreview": "omni_live_tenant_tenant_fb38cc_...", "roleCode": "tenant_admin", "status": "active", "secret": "omni_live_tenant_tenant_fb38cc_tenant_admin_xxxxxxxx" }, "onboarding": { "apiBaseUrl": "/api", "authHeader": "x-omnimodal-api-key", "role": "tenant_admin" } } } } } } } } }, "/v1/public/leads": { "post": { "summary": "Submit commercial lead", "security": [], "responses": { "201": { "description": "Lead created" } } } }, "/v1/multimodal-entries": { "post": { "summary": "Submit a multimodal entry", "security": [ { "OmniModalApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultimodalEntryRequest" }, "example": { "tenantId": "tenant_tenant_fb38cc", "scene": "camera_capture", "intent": "document_scan", "mode": "image", "images": [ { "fileUri": "https://omnimodal.shenliu.cc/uploads/tenant_tenant_fb38cc/upload_7ad5f81e-camera-capture.jpg", "name": "camera-capture.jpg", "mimeType": "image/jpeg", "documentType": "finance.invoice" } ], "businessContext": { "sourceSystem": "mobile_web", "captureSource": "browser_camera", "cameraQualityOverall": "suggest_submit", "cameraBrightnessScore": "72", "cameraSharpnessScore": "61", "cameraCoverageScore": "84" } } } } }, "responses": { "201": { "description": "Entry accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "entryId": "entry_7ad5f81e", "tenantId": "tenant_tenant_fb38cc", "routingStatus": "accepted", "scene": "assistant", "mode": "text", "skillCode": "order_lookup", "linkedIngestionIds": [], "linkedTaskIds": [], "createdAt": "2026-04-17T13:31:00.000Z" } } } } } } } }, "/v1/uploads": { "post": { "summary": "Upload an image or PDF and receive a reusable fileUri", "security": [ { "OmniModalApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "tenantId": "tenant_tenant_fb38cc", "fileName": "camera-capture.jpg", "dataUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...", "purpose": "camera_capture", "sourceSystem": "mobile_web" } } } }, "responses": { "201": { "description": "Upload stored and fileUri returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "fileId": "upload_7ad5f81e", "tenantId": "tenant_tenant_fb38cc", "fileName": "camera-capture.jpg", "mimeType": "image/jpeg", "byteLength": 248193, "purpose": "camera_capture", "sourceSystem": "mobile_web", "fileUri": "https://omnimodal.shenliu.cc/uploads/tenant_tenant_fb38cc/upload_7ad5f81e-camera-capture.jpg", "relativeFileUri": "/uploads/tenant_tenant_fb38cc/upload_7ad5f81e-camera-capture.jpg" } } } } } } } }, "/v1/ingestions": { "post": { "summary": "Create a file ingestion record", "security": [ { "OmniModalApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionRequest" }, "example": { "tenantId": "tenant_tenant_fb38cc", "fileName": "invoice.pdf", "mimeType": "application/pdf", "fileUri": "https://example.com/invoice.pdf", "documentType": "finance.invoice" } } } }, "responses": { "201": { "description": "Ingestion accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "ingestionId": "ing_9ab4b91a", "status": "accepted" } } } } } } } }, "/v1/tasks": { "post": { "summary": "Create async task for ingestion", "security": [ { "OmniModalApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRequest" }, "example": { "tenantId": "tenant_tenant_fb38cc", "ingestionId": "ing_9ab4b91a", "taskType": "document.parse", "providerCode": "aliyun_ocr_general", "sourcePayload": { "executionPreferences": { "strategy": "route_order", "preferredProviderCodes": [ "aliyun_ocr_general" ], "blockedProviderCodes": [], "disableFallbackProviderCodes": [], "ocrReview": { "enabled": true, "providerCode": "qwen_vl_ocr", "reviewLowConfidence": true, "reviewInvalidHighRiskFields": true } } } } } } }, "responses": { "201": { "description": "Task created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "taskId": "task_2f6a3c8d", "status": "queued" } } } } } } } }, "/v1/tasks/{taskId}": { "get": { "summary": "Get task detail", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "taskId": "task_2f6a3c8d", "tenantId": "tenant_tenant_fb38cc", "ingestionId": "ing_9ab4b91a", "taskType": "document.parse", "providerCode": "aliyun_ocr_general", "status": "succeeded", "retryCount": 0, "executionCursor": 0, "nextRunAt": null, "lastErrorMessage": null, "deadLetteredAt": null, "deadLetterReason": null, "operatorNote": null, "createdAt": "2026-04-17T13:32:00.000Z", "updatedAt": "2026-04-17T13:32:10.000Z", "completedAt": "2026-04-17T13:32:10.000Z", "resultId": "res_84f9d7a2" } } } } } } } }, "/v1/tasks/{taskId}/result": { "get": { "summary": "Get task normalized result", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Normalized task result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "resultId": "res_84f9d7a2", "taskId": "task_2f6a3c8d", "tenantId": "tenant_tenant_fb38cc", "schemaType": "finance.invoice", "schemaVersion": "1.0.0", "payload": { "schemaType": "finance.invoice", "schemaVersion": "1.0.0", "extractionConfidence": "high", "fields": { "invoiceNo": "INV-2026-001", "amount": "2088.00" } }, "rawPayloadRef": "mysql:provider_raw_outputs/raw_123", "confidenceLevel": "high", "sourceContext": { "sourceSystem": "mobile_web", "captureSource": "browser_camera", "cameraQualityOverall": "suggest_submit", "cameraBrightnessScore": "72", "cameraSharpnessScore": "61", "cameraCoverageScore": "84" }, "createdAt": "2026-04-17T13:32:10.000Z" } } } } }, "404": { "description": "Result not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tasks/{taskId}/raw-output": { "get": { "summary": "Get task raw provider output", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw provider output" } } } }, "/v1/realtime/sessions": { "post": { "summary": "Create realtime voice session", "security": [ { "OmniModalApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeSessionRequest" }, "example": { "tenantId": "tenant_tenant_fb38cc", "scene": "assistant", "intent": "voice_query", "mode": "voice", "audioConfig": { "codec": "pcm16", "sampleRate": 16000, "channelCount": 1 }, "preflight": true, "businessContext": { "sourceSystem": "web" } } } } }, "responses": { "201": { "description": "Realtime session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "sessionId": "rtsess_2dd7c4c9987a", "tenantId": "tenant_tenant_fb38cc", "scene": "assistant", "intent": "voice_query", "mode": "voice", "status": "created", "audioConfig": { "codec": "pcm16", "sampleRate": 16000, "channelCount": 1 }, "businessContext": { "sourceSystem": "web" }, "asrRouting": { "providerCode": "qwen_realtime_asr", "adapter": "qwen_dashscope", "status": "ready", "fallbackDisabled": true, "upstreamConnectivity": "reachable", "preflightLatencyMs": 183, "checkedAt": "2026-04-17T13:32:00.000Z" }, "runtimeConfig": { "adapter": "qwen_dashscope", "profile": "balanced", "turnDetectionType": "server_vad", "vadThreshold": 0, "silenceDurationMs": 400, "commitTimeoutMs": 15000, "sessionTuningApplied": false, "codecSupport": { "requestedCodec": "pcm16", "accepted": true, "status": "ready", "productionReady": true } }, "audioDiagnostics": { "level": "unknown", "reasonCode": "NO_PCM_AUDIO", "message": "No PCM16 audio chunks were observed by the realtime server.", "appendCount": 0, "pcmAppendCount": 0, "peakPercentMax": 0, "rmsPercentAvg": 0, "silentRatio": 0, "weakRatio": 0 }, "wsUrl": "/v1/realtime/ws?sessionId=rtsess_2dd7c4c9987a&token=xxxxx", "expiresAt": "2026-04-17T14:02:00.000Z", "startedAt": "2026-04-17T13:32:00.000Z" } } } } } } } }, "/v1/realtime/sessions/{sessionId}": { "get": { "summary": "Get realtime session", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime session detail" } } } }, "/v1/realtime/sessions/{sessionId}/events": { "get": { "summary": "Get realtime events", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "sinceCreatedAt", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "eventTypes", "required": false, "schema": { "type": "string" }, "description": "Comma-separated realtime event types to filter." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "order", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Realtime events list. Important diagnostic events include audio.append, audio.commit_failed, transcript.final, and transcript.bridge_failed." } } } }, "/v1/realtime/sessions/{sessionId}/utterances": { "get": { "summary": "Get realtime utterances", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime utterances list" } } } }, "/v1/realtime/sessions/{sessionId}/metrics": { "get": { "summary": "Get realtime session metrics and weak-audio diagnostics", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime metrics summary including weak audio diagnosis and latest final metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardEnvelope" }, "example": { "success": true, "data": { "session": { "sessionId": "rtsess_2dd7c4c9987a", "tenantId": "tenant_tenant_fb38cc", "scene": "assistant", "intent": "voice_query", "mode": "voice", "status": "active" }, "metrics": { "sessionStartSuccess": true, "websocketReadyLatencyMs": 132, "firstPartialLatencyMs": 418, "firstFinalLatencyMs": 1680, "appendCount": 23, "commitCount": 1, "partialCount": 4, "finalCount": 1, "appendRejectedCount": 0, "latestWeakAudioDiagnosis": { "level": "weak", "reasonCode": "PCM_WEAK_SIGNAL", "message": "Server observed weak PCM16 audio. Speech may be too quiet for reliable VAD and realtime ASR.", "peakPercentMax": 1.6, "rmsPercentAvg": 0.3, "silentRatio": 0.12, "weakRatio": 0.74 }, "latestFinalMetrics": { "finalLatencyMs": 1680, "vadFinalizationLatencyMs": 402, "weakAudioDiagnosis": { "level": "weak", "reasonCode": "PCM_WEAK_SIGNAL" } } }, "source": "redis_snapshot" } } } } } } } }, "/v1/tenants/{tenantId}/lexicons": { "get": { "summary": "Get tenant lexicons and effective lexicon bundle", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant lexicons and effective bundle" } } }, "put": { "summary": "Create or update a tenant lexicon", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "industryCode": "logistics", "name": "物流热词补丁", "description": "补充本租户高频业务词。", "priority": 70, "terms": [ { "canonical": "签收回单", "aliases": [ "签收回到", "签售回单" ], "category": "document", "weight": 95, "source": "manual", "status": "active" } ] } } } }, "responses": { "200": { "description": "Tenant lexicon upserted" } } } }, "/v1/tenants/{tenantId}/lexicon-releases": { "get": { "summary": "List tenant lexicon release history", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "lexiconId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Tenant lexicon release history" } } } }, "/v1/tenants/{tenantId}/lexicon-releases/{releaseId}/rollback": { "post": { "summary": "Rollback tenant lexicon to a previous release snapshot", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "releaseId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "reason": "上线后效果不及预期，回滚到前一版。" } } } }, "responses": { "200": { "description": "Tenant lexicon rolled back to target release" } } } }, "/v1/tenants/{tenantId}/transcript-feedback": { "get": { "summary": "List transcript correction feedback and confusion summary", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transcript feedback summary" } } }, "post": { "summary": "Submit corrected transcript feedback", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptFeedbackRequest" }, "example": { "sessionId": "rtsess_xxx", "utteranceId": "utt_xxx", "industryCode": "logistics", "sourceSystem": "ziin", "originalText": "签售回单怎么查询", "correctedText": "签收回单怎么查询", "note": "业务员现场口音导致误识别", "status": "pending_review" } } } }, "responses": { "201": { "description": "Transcript feedback created" } } } }, "/v1/tenants/{tenantId}/realtime-accuracy-overview": { "get": { "summary": "Get tenant realtime transcript accuracy overview", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Tenant realtime transcript accuracy overview" } } } }, "/v1/tenants/{tenantId}/lexicon-benefit-ranking": { "get": { "summary": "Get tenant lexicon benefit ranking by realtime sessions", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Tenant lexicon benefit ranking" } } } }, "/v1/tenants/{tenantId}/realtime-accuracy-timeline": { "get": { "summary": "Get tenant realtime transcript accuracy timeline", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "lookbackDays", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "How many recent sessions to inspect when building the timeline." } ], "responses": { "200": { "description": "Tenant realtime transcript accuracy timeline" } } } }, "/v1/tenants/{tenantId}/lexicon-rollout-impact": { "get": { "summary": "Get lexicon rollout impact before and after baseline", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "lexiconId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "lookbackDays", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 30 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "How many recent sessions to inspect when computing the rollout impact." } ], "responses": { "200": { "description": "Lexicon rollout impact analysis" } } } }, "/v1/tenants/{tenantId}/lexicon-term-impact": { "get": { "summary": "Get lexicon term-level impact attribution", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "lexiconId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "in": "query", "name": "includeArchived", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Lexicon term-level impact attribution" } } } }, "/v1/tenants/{tenantId}/confusion-export": { "get": { "summary": "Export industry confusion package as tenant lexicon seed", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "threshold", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Exported confusion package" } } } }, "/v1/tenants/{tenantId}/confusion-import": { "post": { "summary": "Import industry confusion package into tenant lexicon", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "industryCode": "business_work", "threshold": 2, "name": "business_work 高频错词自动导入", "priority": 76 } } } }, "responses": { "201": { "description": "Confusion package imported into tenant lexicon" } } } }, "/v1/tenants/{tenantId}/accuracy-weekly-briefing": { "get": { "summary": "Get weekly realtime accuracy operations briefing", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Weekly realtime accuracy briefing" } } } }, "/v1/tenants/{tenantId}/accuracy-weekly-briefing/archive": { "post": { "summary": "Archive weekly realtime accuracy briefing into audit trail", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "industryCode": "business_work", "scene": "assistant", "limit": 300 } } } }, "responses": { "201": { "description": "Weekly briefing archived" } } } }, "/v1/tenants/{tenantId}/industry-accuracy-leaderboard": { "get": { "summary": "Get cross-industry realtime accuracy leaderboard", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Cross-industry accuracy leaderboard" } } } }, "/v1/tenants/{tenantId}/accuracy-weekly-briefing-archives": { "get": { "summary": "List archived weekly accuracy briefings from audit trail", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Archived weekly briefings" } } } }, "/v1/tenants/{tenantId}/industry-seed-package": { "get": { "summary": "Build industry seed package from top terms and confusion export", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Industry seed package" } } } }, "/v1/tenants/{tenantId}/industry-seed-import": { "post": { "summary": "Import industry seed package into tenant lexicon", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "industryCode": "business_work", "scene": "assistant", "priority": 74 } } } }, "responses": { "201": { "description": "Industry seed package imported" } } } }, "/v1/tenants/{tenantId}/low-confidence-sample-pool": { "get": { "summary": "Get low-confidence realtime transcript sample pool", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Low-confidence sample pool" } } } }, "/v1/tenants/{tenantId}/low-confidence-sample-feedback": { "post": { "summary": "Convert a low-confidence sample into transcript feedback", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "sessionId": "rtsess_xxx", "utteranceId": "rtutt_xxx", "industryCode": "business_work", "originalText": "客户跟近怎么查", "correctedText": "客户跟进怎么查", "note": "低置信度样本池人工修正" } } } }, "responses": { "201": { "description": "Low-confidence sample converted into transcript feedback" } } } }, "/v1/tenants/{tenantId}/industry-seed-recommendation": { "get": { "summary": "Get recommendation for whether to import current industry seed package", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Industry seed import recommendation" } } } }, "/v1/tenants/{tenantId}/industry-priority-queue": { "get": { "summary": "Get industry priority queue for operations", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Industry priority queue" } } } }, "/v1/tenants/{tenantId}/transcript-feedback-candidates/promote": { "post": { "summary": "Promote one transcript feedback candidate into tenant lexicon", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "industryCode": "business_work", "originalText": "客户跟近", "correctedText": "客户跟进", "lexiconName": "business_work-feedback-promotions" } } } }, "responses": { "201": { "description": "Transcript feedback candidate promoted" } } } }, "/v1/tenants/{tenantId}/industry-ops-work-orders": { "get": { "summary": "Generate industry operations work orders", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scene", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Industry operations work orders" } } } }, "/v1/tenants/{tenantId}/industry-ops-work-orders/{workOrderId}/start": { "post": { "summary": "Mark an industry operations work order as in progress", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "workOrderId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "note": "已开始处理该行业任务单。" } } } }, "responses": { "200": { "description": "Industry operations work order started" } } } }, "/v1/tenants/{tenantId}/industry-ops-work-orders/{workOrderId}/complete": { "post": { "summary": "Complete an industry operations work order", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "workOrderId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "note": "已完成行业词包导入与低置信度复盘。", "autoArchive": true } } } }, "responses": { "200": { "description": "Industry operations work order completed" } } } }, "/v1/tenants/{tenantId}/industry-ops-work-orders/{workOrderId}/archive": { "post": { "summary": "Archive an industry operations work order", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "workOrderId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "note": "该行业已处理完毕，先归档观察。", "archivedReason": "priority_cooled_down" } } } }, "responses": { "200": { "description": "Industry operations work order archived" } } } }, "/v1/tenants/{tenantId}/confusion-ranking": { "get": { "summary": "Get tenant top transcript confusion ranking", "security": [ { "OmniModalApiKey": [] } ], "parameters": [ { "in": "path", "name": "tenantId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "industryCode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Tenant confusion ranking" } } } } } } }