Juvoly V1 API Documentation

This page provides an overview of how to interact with our v1 API. For detailed code examples, check out the following links:

• Python

Overview

To use the Juvoly API, follow these two steps:

1. Create a session: Use your client ID and API key to establish a session.
2. Open a WebSocket: Initiate the WebSocket for the session to begin transcribing and summarizing.

See an overview of the interaction below:

Create a Session

To begin, you will need a valid API key. If you don’t have one, you can request it by emailing info@juvoly.nl.

Note:
Your API key is private and should not be shared with anyone outside your organization. Ensure that end-users are not able to extract the API key from your application if it is being executed client side.

Sending the Request

To create a session, send an HTTP POST request to the following endpoint:
https://ai.juvoly.nl/api/authentication/session

You’ll need to provide the following headers with your request:

X-Juvoly-Api-Key: <api-key>
X-Juvoly-Client-Id: <client-id>
Content-Type:: application/json

The body should be an empty json object:

{}

Processing the response

After successfully requesting access, you should receive an HTTP 200 OK response with the following body:

{
    "clientId": "<client-id>",
    "sessionId": "<session-id>",
    "sessionCreateTime": "<ISO 8601 timestamp>",
    "sessionClaimTime": null
}

The most important value in the response is the sessionId, which you will need to establish a WebSocket connection later.

Note:

• The sessionId expires ten minutes after creation or immediately upon opening a WebSocket connection.
• As the sessionId is sensitive information, do not share it with third parties. It is fine to store it in memory on the frontend.

Open a WebSocket

After obtaining the sessionId, you can establish a WebSocket connection. This can be done directly from the client, such as a web browser. There’s no need to redirect audio through your back-end.

Create the Connection

To create the connection, use the following WebSocket URL:
wss://ai.juvoly.nl/ws/speech/<client id>/<sessionId>

After successfully connecting, wait for a ready message from the server before sending any other data. The message will look like this:

{
    "type": "ready"
}

Start Transcribing

When you receive the “ready” message, you can begin sending audio blobs over the WebSocket connection. The audio data can be transmitted directly as raw bytes, without any additional protocol. For more details on how to send audio blobs, check out the language-specific examples linked at the beginning of this page.

After sending audio blobs, you will begin receiving transcription fragments in real time. The transcript message contains two parts:

• Completed: The portion of the transcription that has been fully processed and is considered complete.
• Buffer: The text currently in progress. This is subject to change as more audio is processed.

The buffered text will be included in subsequent messages as part of the completed content once it has been fully processed.

{
    "type": "transcript",
    "transcript":
    {
        "completed":
        [
            {
                "idx": 49,
                "start": 8.48,
                "end": 9.12,
                "sentence": "Goedemiddag.",
                "speaker": null,
                "words":
                [
                    {
                        "idx": 0,
                        "start": 8.48,
                        "end": 9.12,
                        "word": "Goedemiddag."
                    }
                ]
            }
        ],
        "buffer":
        [
            {
                "idx": 50,
                "start": 9.84,
                "end": 10.16,
                "sentence": "Wat heeft",
                "speaker": null,
                "words":
                [
                    {
                        "idx": 0,
                        "start": 9.84,
                        "end": 9.92,
                        "word": "wat"
                    },
                    {
                        "idx": 0,
                        "start": 10.08,
                        "end": 10.16,
                        "word": "heeft"
                    }
                ]
            }
        ]
    }
}

Request Summarization

To request a summarization, send a request over the WebSocket connection. The request format should be as follows:

{
    "type": "summarize",
    "request": {
        "modelSize": "large",
        "template": "soap" | "meeting" | "dictation"
        "episodeCount": undefined
    }
}

Shortly after submitting your request, you will receive a message containing the summary. It will look like the example below:

{
    "type": "summarization",
    "summarization":
    {
        "template": "soap",
        "result":
        {
            "episodes":
            [
                {
                    "S": "Keelpijn en hoofdpijn al 2 weken.",
                    "O": "",
                    "E": "Mogelijke infectie van de keel.",
                    "P": "Antibiotica voorgeschreven."
                },
                {
                    "S": "Plekje op de voet, behandeling gewenst.",
                    "O": "",
                    "E": "Niet gedefinieerd, verdere evaluatie nodig.",
                    "P": "Verwijzing naar dermatoloog."
                }
            ]
        }
    }
}