WebSocket API V2 Configuration

Overview

The V2 WebSocket API provides a structured, protocol-versioned messaging system for text-to-sign-language video translation. This is the current recommended protocol.

Connection Details

Connection URL

Authentication

• Production: Use platform authentication (API Gateway tokens, cookies, etc.)

Message Schema

Client → Server Request

{
"protocol": {
  "name": "string",
  "version": "string"
},
"content": {
  "type": "text",
  "data": "string"
},
"output": {
  "format": "hls",
  "delivery": {
    "method": "stream"
  }
},
"context": {
  "application": "string"
}
}

Server → Client Response

{
"protocol": {
  "name": "string",
  "version": "string"
},
"success": true,
"message": "string"
}

Configuration Options

Format Options:

• hls: HTTP Live Streaming — suitable for adaptive bitrate streaming, recommended for live translation scenarios
• mp4: MPEG-4 video file — suitable for download and offline playback

Delivery Methods:

• stream: Real-time streaming delivery — recommended for HLS format
• download: File download delivery — recommended for MP4 format

Internal Metadata (Auto-configured)

The V2 handler automatically configures the following metadata for video processing:

Message Processing

V2 Protocol Detection

The server automatically detects V2 messages by the presence of the top-level "protocol" field. Both V1 and V2 messages can be sent on the same connection.

Live Translation Mode

All V2 messages are processed as live translations, which means:

• No profanity filtering
• No rate limiting
• No word count validation
• Optimized for real-time performance

Complete Example

Request Message

{
"protocol": {
  "name": "signapse-client",
  "version": "2.0"
},
"content": {
  "type": "text",
  "data": "Welcome to our text-to-video API service"
},
"output": {
  "format": "hls",
  "delivery": {
    "method": "stream"
  }
},
"context": {
  "application": "media"
}
}

Success Response

{
"protocol": {
  "name": "signapse-client",
  "version": "2.0"
},
"success": true,
"message": "Video processing for Welcome to our text-to-video API service"
}

Error Response

{
"protocol": {
  "name": "signapse-client",
  "version": "2.0"
},
"success": false,
"message": "Failed to generate picture-in-picture, please try again"
}

JavaScript Client Example

const ws = new WebSocket("wss://ai.api.production.signapsesolutions.com");

ws.onopen = () => {
console.log("WebSocket connected");

const message = {
  protocol: {
    name: "signapse-client",
    version: "2.0"
  },
  content: {
    type: "text",
    data: "Hello world"
  },
  output: {
    format: "hls",
    delivery: {
      method: "stream"
    }
  },
  context: {
    application: "media"
  }
};

ws.send(JSON.stringify(message));
};

ws.onmessage = (event) => {
const response = JSON.parse(event.data);
console.log("Response:", response);

if (response.success) {
  console.log("Translation successful:", response.message);
} else {
  console.error("Translation failed:", response.message);
}
};

ws.onerror = (error) => {
console.error("WebSocket error:", error);
};

ws.onclose = () => {
console.log("WebSocket connection closed");
};

TypeScript Type Definitions

interface ProtocolInfo {
name: string;
version: string;
}

interface Content {
type: "text";
data: string;
}

interface OutputDelivery {
method: "stream" | "download";
}

interface Output {
format: "hls" | "mp4";
delivery: OutputDelivery;
}

interface Context {
application: string;
}

interface WebSocketMessageV2 {
protocol: ProtocolInfo;
content: Content;
output: Output;
context: Context;
}

interface WebSocketResponseV2 {
protocol: ProtocolInfo;
success: boolean;
message: string;
}

Media Delivery

Video output is delivered via presigned URLs. The WebSocket connection receives:

• Status acknowledgment messages
• Processing progress updates
• Completion notifications

The actual video media is retrieved through presigned URLs generated by backend services according to the specified output configuration.

Stream Delivery (HLS)

For streaming delivery with HLS format:

1. Receive acknowledgment of processing
2. Obtain presigned URL for HLS manifest
3. Poll or watch the HLS manifest/segments
4. Stream video content to client

Recommended for: Live translation, real-time scenarios, adaptive streaming

Download Delivery (MP4)

For download delivery with MP4 format:

1. Receive acknowledgment of processing
2. Wait for video generation completion
3. Obtain presigned URL for complete MP4 file
4. Download video file for playback

Recommended for: Archived content, offline viewing, complete file access

Advantages Over V1

Migration from V1

Key Differences

1. Protocol Field: V2 requires explicit protocol identification
2. Content Structure: sentence → content.data
3. Output Configuration: metadata.responseFormat → output.format
4. Context Information: New context object for application routing

Migration Example

V1 message:

{
"action": "LiveTranslation",
"sentence": "Hello world",
"metadata": {
  "responseFormat": "hls"
}
}

V2 equivalent:

{
"protocol": {
  "name": "your-app",
  "version": "2.0"
},
"content": {
  "type": "text",
  "data": "Hello world"
},
"output": {
  "format": "hls",
  "delivery": {
    "method": "stream"
  }
},
"context": {
  "application": "media"
}
}

Best Practices

1. Protocol Versioning: Use semantic versioning for your protocol name and version
2. Error Handling: Always handle both success and error responses
3. Connection Management: Implement reconnection logic for network interruptions
4. Format Selection:
   • Use HLS with stream delivery for live scenarios
   • Use MP4 with download delivery for on-demand content
5. Context Information: Provide meaningful application context for analytics and routing

Troubleshooting