Heidi API
Transcription

Transcription

Initialise audio transcription

Method: POST

Path: /sessions/{session_id}/restful-segment-transcription

Description: Initialise an audio transcription

Request

POST /sessions/1234567890/restful-segment-transcription
Authorization: Bearer <your_token>

Response

{
  "recording_id": "123"
}

Upload audio to transcribe

Method: POST

Path: /sessions/{session_id}/restful-segment-transcription/{recording_id}:transcribe

Description: Upload an audio chunk to transcribe. Even though it's possible to upload an entire consult audio at once, we recommend splitting the audio every 45s-1min to increase transcription accuracy.

Preferred file types: Most audio file types are supported, however .mp3, .ogg are preferred as they generate better quality transcriptions.

Request

POST /sessions/1234567890/restful-segment-transcription/123:transcribe
Authorization: Bearer <your_token>
Content-Type: multipart/form-data
 
{
  "file": "audio.mp3",
  "index": "0"
}

Response

{
  "is_success": true
}

End audio transcription

Method: POST

Path: /sessions/{session_id}/restful-segment-transcription/{recording_id}:finish

Description: Complete an audio transcription

Request

POST /sessions/1234567890/restful-segment-transcription/123:finish
Authorization: Bearer <your_token>

Response

{
  "is_success": true
}

Retrieve transcript

Method: GET

Path: /sessions/{session_id}/transcript

Description: Retrieve the transcript for a session.

Request

GET /sessions/1234567890/transcript
Authorization: Bearer <your_token>

Response

{
  "transcript": "Transcript text..."
}

Retrieve live transcript

Method: GET

Path: /open-api/sessions/{session_id}/transcript/live

Description: Get the session's live transcript with chunks. This endpoint returns transcript data from multiple recording sources (user uploaded, live recording, and backup) along with their chunked segments.

Query Parameters

ParameterTypeRequiredDefaultDescription
recording_statusstringNoin_progressStatus of the recording. Possible values: in_progress, complete

Request

GET /open-api/sessions/1234567890/transcript/live?recording_status=in_progress
Authorization: Bearer <your_token>

Response

{
  "response": {
    "user_uploaded": [
      {
        "id": "recording_123",
        "chunks": [
          {
            "id": 1,
            "status": "COMPLETE",
            "transcript": "Patient presents with...",
            "duration": 45.5
          },
          {
            "id": 2,
            "status": "IN_PROGRESS",
            "transcript": "The patient reports...",
            "duration": 30.2
          }
        ],
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "live": [],
    "backup": [],
    "transcript_in_use": "user_uploaded",
    "transcript": "Patient presents with... The patient reports..."
  }
}

Response Schema

response (object): The main response object containing transcript data

  • user_uploaded (array): Array of chunked recordings from user-uploaded audio
  • live (array): Array of chunked recordings from live recording
  • backup (array): Array of chunked recordings from backup audio
  • transcript_in_use (string|null): Indicates which transcript source is currently being used (user_uploaded, live, or backup)
  • transcript (string|null): The full concatenated transcript text

Chunked Recording Object:

  • id (string): Unique identifier for the recording
  • chunks (array): Array of transcript chunks
  • created_at (string|null): ISO 8601 timestamp of when the recording was created

Chunk Object:

  • id (integer): Unique identifier for the chunk
  • status (string): Transcription status of the chunk
  • transcript (string|null): The transcribed text for this chunk
  • duration (number): Duration of the audio chunk in seconds
CodingConsult notes