Skip to content

REST API SDK Getting Started

This guide shows the shared setup used by REST API SDK examples.

Verified example flow

Each language guide demonstrates the same end-to-end workflow:

  • Upload a local audio file
  • Start a transcription job with the generated UploadAndTranscribe operation
  • Poll the transcription job until it reaches a terminal state
  • Print the final transcription or the job errors

Prerequisites

  • A running Koldan server
  • A valid API key
  • A downloaded SDK archive for your language
  • A local audio file to transcribe

Shared Environment Variables

Use the same three environment variables in every example.

$env:KOLDAN_BASE_URL = "http://localhost:8193"
$env:KOLDAN_API_KEY = "YOUR_API_KEY"
$env:KOLDAN_FILE_PATH = "C:\absolute\path\to\sample-audio.wav"

export KOLDAN_BASE_URL="http://localhost:8193"
export KOLDAN_API_KEY="YOUR_API_KEY"
export KOLDAN_FILE_PATH="/absolute/path/to/sample-audio.wav"

Upload And Transcribe Request

The examples call POST /api/v1/speech-services/transcriptions/upload through the generated SDK method for each language.

The verified request uses these values:

  • file: the local WAV file content
  • name: a display name such as meeting-recording
  • path: /incoming-audio/
  • metadata: a JSON string such as {"source":"upload","type":"meeting-recording"}
  • tags: a JSON string such as ["meeting","transcription"]
  • transcription: a JSON string such as:
{
  "model": "general",
  "language": {
    "defaultLanguageCode": "he"
  },
  "punctuation": false,
  "capitalization": false
}
  • diarization: a JSON string with enabled: false

Provide uri instead of file only when you want Koldan to import a remote file.

Multipart request fields

transcription and diarization are sent as JSON-encoded strings because the upload endpoint uses multipart form data.

Polling For Completion

UploadAndTranscribe returns both the uploaded file and the created transcription job. After creating the job, the examples poll the generated getJob operation until the job reaches one of these terminal states:

  • COMPLETED
  • FAILED
  • CANCELLED

When the job completes successfully, the transcript is available in job.result.text. When the job fails, the examples print job.errorCode and job.errors.

Install A REST API SDK

Download the REST API SDK archive for your language from SDK Overview, extract it, and follow the language-specific setup guide:

For live microphone or PCM streaming integrations, use the separate C# WebSocket SDK.

Authentication

Koldan accepts API key authentication through the X-API-Key header. Depending on the generated client, you will configure either:

  • the generated apiKey security scheme value, or
  • the X-API-Key header entry expected by that SDK

Each language page shows the exact client configuration call.