Transcribe

The /transcribe endpoint allows you to convert medical audio recordings into structured clinical notes. It uses advanced speech recognition technology to transcribe the audio and then formats the transcription into a structured clinical note based on the specified template.

Endpoint

POST /transcribe

Authentication

This endpoint requires authentication using your API key. Include your API key in the x-api-key header with all requests. See Authentication for more details.

Request

The request must be sent as multipart/form-data with the following parameters:

Parameter	Type	Required	Description
`file`	File	Yes	The audio file to transcribe. Must be one of the supported formats and under 100MB.
`note_type`	String	No	The clinical note type that determines the appropriate template and sections. See Note Types for available options.
`template`	String	No	The specific template to use for the medical note. If provided, this overrides the default template for the selected `note_type`. See Note Templates for available options. Defaults to `SOAP` if not provided.
`language`	String	No	The language of the audio. See Language Support for available options. Defaults to `en` (English).

Response

The response is a JSON object with the following structure:

{
  "note": {
    "title": "Medical Consultation Note",
    "sections": [
      {
        "key": "SUBJECTIVE",
        "title": "Subjective",
        "content": "Patient reports chest pain for the past 3 days..."
      },
      {
        "key": "OBJECTIVE",
        "title": "Objective",
        "content": "BP 140/90, HR 88, RR 18, Temp 98.6F..."
      },
      {
        "key": "ASSESSMENT",
        "title": "Assessment",
        "content": "1. Acute coronary syndrome - likely..."
      },
      {
        "key": "PLAN",
        "title": "Plan",
        "content": "1. Admit to cardiology service..."
      }
    ]
  }
}

Field	Type	Description
`note`	Object	The structured medical note generated from the transcription.
`note.title`	String	The title of the medical note.
`note.sections`	Array	An array of sections in the note. The specific sections depend on the template used.
`note.sections[].key`	String	The identifier for the section (e.g., "SUBJECTIVE", "OBJECTIVE").
`note.sections[].title`	String	The display title for the section.
`note.sections[].content`	String	The content of the section.

Key Concepts

Note Types

The note_type parameter allows you to specify the type of clinical note you want to generate. Each note type is associated with a default template that structures the output in a way that's appropriate for that type of clinical documentation.

Available note types:

Note Type	Description	Default Template
`PROGRESS_NOTE`	Documentation of a patient's progress during treatment	`SOAP`
`ADMISSION_NOTE`	Documentation of a patient's initial hospital admission	`APSO`
`ED_NOTE`	Documentation of an emergency department visit	`CHEDDAR`
`DISCHARGE_SUMMARY`	Summary of a patient's hospital stay upon discharge	`MULTIPLE_SECTIONS`
`CONSULT_NOTE`	Documentation of a specialist consultation	`APSO`
`NURSING_NOTE`	Documentation by nursing staff	`PIE`
`BEHAVIORAL_HEALTH_NOTE`	Documentation of behavioral health services	`BIRP`
`DIETITIAN_NOTE`	Documentation by a dietitian	`ADIME`

Note Templates

The template parameter allows you to specify the structure of the generated clinical note. If provided, it overrides the default template associated with the selected note_type.

Available templates:

Template	Description	Sections
`SOAP`	Subjective, Objective, Assessment, Plan	SUBJECTIVE, OBJECTIVE, ASSESSMENT, PLAN
`APSO`	Assessment, Plan, Subjective, Objective (prioritizes assessment and plan)	ASSESSMENT, PLAN, SUBJECTIVE, OBJECTIVE
`MULTIPLE_SECTIONS`	Comprehensive note with multiple detailed sections	CHIEF_COMPLAINT, HISTORY_OF_PRESENT_ILLNESS, PAST_MEDICAL_HISTORY, PHYSICAL_EXAM, ASSESSMENT, PLAN
`CHEDDAR`	Chief complaint, History, Examination, Differential, Decision, Action, Review	CHIEF_COMPLAINT, HISTORY, EXAMINATION, DIFFERENTIAL, DECISION, ACTION, REVIEW
`DAP`	Data, Assessment, Plan	DATA, ASSESSMENT, PLAN
`PIE`	Problem, Intervention, Evaluation	PROBLEM, INTERVENTION, EVALUATION
`SBAR`	Situation, Background, Assessment, Recommendation	SITUATION, BACKGROUND, ASSESSMENT, RECOMMENDATION
`BIRP`	Behavior, Intervention, Response, Plan	BEHAVIOR, INTERVENTION, RESPONSE, PLAN
`DAR`	Data, Action, Response	DATA, ACTION, RESPONSE
`ADIME`	Assessment, Diagnosis, Intervention, Monitoring, Evaluation	ASSESSMENT, DIAGNOSIS, INTERVENTION, MONITORING, EVALUATION

Audio Processing

The /transcribe endpoint supports the following audio formats:

audio/mpeg (MP3)
audio/mp4 (M4A)
audio/wav (WAV)
audio/x-wav (WAV)
audio/vnd.wave (WAV)
audio/wave (WAV)
audio/x-pn-wav (WAV)
audio/webm (WEBM)
audio/ogg (OGG)
audio/flac (FLAC)
audio/x-flac (FLAC)
audio/aac (AAC)
audio/x-aac (AAC)

The maximum file size is 100MB. Larger files will be rejected with a 413 error.

The service performs diarization, which means it identifies different speakers in the audio and labels them in the transcript (e.g., "Speaker 1", "Speaker 2"). This helps maintain the conversational context in the generated note.

Language Support

The /transcribe endpoint supports the following languages:

Language Code	Language Name
`en`	English (default)
`es`	Spanish
`pt`	Portuguese

The language parameter affects both the speech recognition model used for transcription and the language of the generated clinical note. For optimal results, ensure the specified language matches the language spoken in the audio.

Medical Content Validation

The API checks if the transcribed content contains relevant medical discussion. If the content is not medical in nature (e.g., a casual conversation unrelated to healthcare), the API will return a 400 error with a message indicating that the audio does not contain relevant medical content.

This validation helps ensure that the service is used for its intended purpose and prevents processing of non-medical audio.

Integration Examples

cURL

curl -X POST https://api.knidian.ai/transcribe \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@patient_consultation.mp3" \
  -F "note_type=PROGRESS_NOTE" \
  -F "language=en"

Python

import requests

url = "https://api.knidian.ai/transcribe"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

files = {
    "file": ("patient_consultation.mp3", open("patient_consultation.mp3", "rb"), "audio/mpeg")
}

data = {
    "note_type": "PROGRESS_NOTE",
    "language": "en"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Node.js

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const path = require('path');

async function transcribeAudio() {
  const form = new FormData();
  form.append('file', fs.createReadStream(path.resolve('./patient_consultation.mp3')));
  form.append('note_type', 'PROGRESS_NOTE');
  form.append('language', 'en');

  try {
    const response = await axios.post('https://api.knidian.ai/transcribe', form, {
      headers: {
        ...form.getHeaders(),
        'x-api-key': 'YOUR_API_KEY'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response ? error.response.data : error.message);
  }
}

transcribeAudio();

Error Handling

Status Code	Description
400	Bad Request - Invalid parameters or the audio does not contain relevant medical content
401	Unauthorized - Invalid or missing API key
402	Payment Required - Subscription limit reached or payment required
413	Payload Too Large - Audio file exceeds the 100MB limit
415	Unsupported Media Type - Unsupported audio format
500	Internal Server Error - An unexpected error occurred on the server
503	Service Unavailable - The service is temporarily unavailable

Usage Tracking

The API tracks the following metrics for each transcription request:

Request duration
Audio duration (in seconds)
Knidian's AI Engine processing time
Success/failure status

These metrics are used for billing purposes and to improve the service. They are associated with your API key and organization.

Endpoint​

Authentication​

Request​

Response​

Key Concepts​

Note Types​

Note Templates​

Audio Processing​

Language Support​

Medical Content Validation​

Integration Examples​

cURL​

Python​

Node.js​

Error Handling​

Usage Tracking​