diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index e8854c8..53e7c87 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -2012,6 +2012,46 @@ paths: $ref: '#/components/responses/ServiceUnavailable' security: - auth_header: [] + get: + tags: + - VoiceAPI + summary: Request Reconnection + operationId: requestReconnection + parameters: + - name: token + in: query + required: true + description: The latest ephemeral token obtained for the stream. + schema: + type: string + example: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K' + responses: + 200: + description: Successfully obtained streaming URL and reconnection token. + content: + application/json: + schema: + $ref: '#/components/schemas/VoiceStreamingResponse' + example: + streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect' + token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K' + session_id: '4f911080-cfe2-41d4-8269-0e6ec15a0354' + 400: + $ref: '#/components/responses/BadRequest' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/Forbidden' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [] components: parameters: DocumentID: diff --git a/api-reference/voice.mdx b/api-reference/voice.mdx index ff35721..ce40ea0 100644 --- a/api-reference/voice.mdx +++ b/api-reference/voice.mdx @@ -132,7 +132,7 @@ The Voice API uses a two-step flow to initiate streaming. ```json { "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect", - "token": , + "token": , } ``` @@ -147,7 +147,7 @@ The Voice API uses a two-step flow to initiate streaming. See the [Request Stream](/api-reference/voice/request-stream) documentation for details. - Use the received URL to establish a WebSocket connection to `wss://api.deepl.com/v3/voice/realtime/connect?token=`. + Use the received URL to establish a WebSocket connection to `wss://api.deepl.com/v3/voice/realtime/connect?token=`. This step handles exchanging JSON messages on the WebSocket connection: * Sending audio data * Receiving transcriptions and translations in real-time @@ -215,6 +215,36 @@ sequenceDiagram `par` means parallel execution and `loop` means looped execution. +## Reconnecting + +Network connections are inherently unreliable. +Disconnections are unavoidable and must be planned for. +In case your stream gets disconnected, request a new authentication token to pick up where you left off. +Make a GET request `v3/voice/realtime?token=`. +The response will look like this: + +```json +{ + "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect", + "token": , +} +``` + +Use the received URL and token to establish a new WebSocket connection. +Should another reconnection become necessary, repeat the procedure. + +See the [Reconnect Stream](/api-reference/voice/reconnect-stream) documentation for details. + + +Always use the latest authentication token to request a new authentication token. +The use of outdated tokens will invalidate your session for security reasons. + + + +If you still have an active connection, requesting a reconnection token will disconnect you. + + + ## Usage Examples You can find a reference usage example for python at our @@ -230,3 +260,4 @@ to interact with the API. * Recommended chunk duration: 50-250 milliseconds for low latency * Audio stream speed: maximum 2x real-time * Timeout: If no data is received for 30 seconds, the session will be terminated +* Using any given token more than once to establish a WebSocket connection will terminate associated the session immediately for security reasons. diff --git a/api-reference/voice/reconnect-stream.mdx b/api-reference/voice/reconnect-stream.mdx new file mode 100644 index 0000000..acee0d8 --- /dev/null +++ b/api-reference/voice/reconnect-stream.mdx @@ -0,0 +1,4 @@ +--- +openapi: get /v3/voice/realtime +title: "Reconnect Stream" +--- diff --git a/docs.json b/docs.json index 4c05ebc..50713f3 100644 --- a/docs.json +++ b/docs.json @@ -214,7 +214,8 @@ "pages": [ "api-reference/voice", "api-reference/voice/request-stream", - "api-reference/voice/websocket-streaming" + "api-reference/voice/websocket-streaming", + "api-reference/voice/reconnect-stream" ] } ]