Notes Transcription API

The Dorsum Transcription API allows you to convert audio consultations into clinical notes by sending chunks of audio data via HTTP POST requests.

Important Notes

⚠️ Critical Requirements:

Chunks MUST be exactly 30 seconds in length
Shorter or longer chunks will result in increased costs or latency
Non-compliant chunk lengths may lead to API access being blocked

Session Management

The API requires a consistent session ID for each recording to maintain context and enable continuity. You must:

Generate a UUID v4 at the start of each new recording session
Pass this same UUID with every chunk of that recording
Store this UUID on your end for potential session recovery

Transcribe Endpoint

POST URL: POST /api/consultations/transcribe

Headers

The following headers are required for authentication:

Content-Type: Must be set to application/json
Api-Key: Your unique API key
Client-Key: Your client-specific key

Request Body

{
    "session_id": string,           // UUID v4 for the recording session
    "chunk": number[],              // Array of audio samples
    "is_final": boolean,            // Whether this is the final chunk
    "previous_transcript": string,   // Previous transcription result
    "language": string,             // Input language (default: "en")
    "output_format": string,        // "text" or "json"
}

Response Format

For intermediate chunks:

{
    "message": "Chunk received successfully",
    "code": 200,
    "transcription": string
}

For final chunks:

{
    "message": "Clinical note generated.",
    "code": 200,
    "task_id": string,
    "clinical_notes": string,        // Clinical notes in requested format
    "full_transcript": string        // Complete transcript of the session
}

Audio Requirements

Format: Raw PCM audio data converted to array of numbers
Sample Rate: Must be exactly 16000 Hz
Channels: Mono
Chunk duration: Must be exactly 30 seconds
Chunk size: Must be exactly 480000 samples (16000 * 30)

Implementation Guide

Setting Up Headers

const headers = {
    'Content-Type': 'application/json',
    'Api-Key': 'YOUR_API_KEY',
    'Client-Key': 'YOUR_CLIENT_KEY'
};

Managing Audio Buffer

const SAMPLE_RATE = 16000;
const CHUNK_DURATION_MS = 30000;  // Exactly 30 seconds
const CHUNK_SIZE = SAMPLE_RATE * (CHUNK_DURATION_MS / 1000);  // 480000 samples

function processBuffer(buffer) {
    // Only process when we have exactly 30 seconds of audio
    if (buffer.length >= CHUNK_SIZE) {
        const chunk = buffer.slice(0, CHUNK_SIZE);
        const remainingBuffer = buffer.slice(CHUNK_SIZE);
        return { chunk, remainingBuffer };
    }
    return { chunk: null, remainingBuffer: buffer };
}

Sending Audio Chunks

async function sendAudioChunk(chunk, sessionId, isFinal = false, previousTranscript = '') {
    // Validate chunk length
    if (chunk.length !== CHUNK_SIZE && !isFinal) {
        throw new Error(`Chunk must be exactly ${CHUNK_SIZE} samples (30 seconds)`);
    }

    const requestBody = {
        session_id: sessionId,
        chunk,
        is_final: isFinal,
        previous_transcript: previousTranscript,
        language: 'en',
        output_format: 'text'  // or 'json'
    };

    try {
        const response = await fetch('/api/consultations/transcribe', {
            method: 'POST',
            headers,
            body: JSON.stringify(requestBody)
        });

        if (!response.ok) {
            throw new Error('Failed to send chunk');
        }

        return await response.json();
    } catch (error) {
        throw new Error(`Error sending chunk: ${error.message}`);
    }
}

Error Handling

The API may return the following error responses:

401 Unauthorized: Invalid or missing API key or client key
400 Bad Request: Invalid request format, parameters, or chunk length
500 Internal Server Error: Server-side processing error

Best Practices

Chunk Management

Ensure chunks are EXACTLY 30 seconds
Don't send chunks that are too short or too long
Process audio in real-time to maintain chunk size
Only send non-silent chunks (except final chunk)

Session Management

Generate UUID v4 for each new recording session
Store session IDs securely for potential recovery
Use the same session ID for all chunks of a recording

Error Handling

Implement retry logic for failed requests
Use appropriate timeouts (60 seconds recommended)
Queue unprocessed chunks for retry
Validate chunk length before sending

Performance Optimization

Process audio asynchronously
Use ScriptProcessorNode with appropriate buffer size
Monitor and log chunk sizes
Clean up resources after recording completes