Transcriptions

Manage speech-to-text transcription jobs. Submit audio files for transcription, monitor job progress, retrieve results in multiple formats, configure webhooks for completion notifications, and manage the job lifecycle.

Base path: /api/v1/speech-services/transcriptions

List Transcription Jobs

GET /api/v1/speech-services/transcriptions

Requires Authentication - Scopes: speech:transcriptions:read

Retrieve a paginated list of transcription jobs. By default returns only the current user's jobs. When fileId is specified, returns all transcriptions for that file (requires speech:files:read access to the file, enabling discovery of transcriptions on shared files).

Query Parameters

curl -X GET "https://koldan.dixilang.com/api/v1/speech-services/transcriptions?page=0&size=20&status=COMPLETED" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/transcriptions",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"page": 0, "size": 20, "status": "COMPLETED"}
)
print(resp.json())

SpeechServiceTranscriptionJobsListResponse

{
  "jobs": [
    { "id": "d1e2f3a4-...", "status": "COMPLETED", ... }
  ],
  "size": 1,
  "total": 1
}

Upload and Transcribe

POST /api/v1/speech-services/transcriptions/upload

Requires Authentication - Scopes: speech:files:write, speech:transcriptions:write; speech:translations:write when translations are requested

Rate Limited - Transcription admission and file upload limits, plus one Text Services execution and one Speech Services translation creation unit per target.

Upload a media file (or import from URI) and immediately start a transcription job in one step. Provide either file (multipart binary) or uri (string), but not both. Optional summary and translations schedule independent jobs after transcription completes.

Multipart Form Parts

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/transcriptions/upload \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -F "file=@meeting-2026-04-01.wav" \
  -F "name=meeting-recording" \
  -F 'transcription={"model":"hebrew-general","language":{"defaultLanguageCode":"he"}}' \
  -F 'diarization={"enabled":true,"mode":"SPEAKER","maxSpeakers":4}'

import requests, json

with open("meeting-2026-04-01.wav", "rb") as f:
    resp = requests.post(
        "https://koldan.dixilang.com/api/v1/speech-services/transcriptions/upload",
        headers={"Authorization": f"Bearer {JWT}"},
        files={"file": ("meeting-2026-04-01.wav", f)},
        data={
            "name": "meeting-recording",
            "transcription": json.dumps({"model": "hebrew-general", "language": {"defaultLanguageCode": "he"}}),
            "diarization": json.dumps({"enabled": True, "mode": "SPEAKER", "maxSpeakers": 4})
        }
    )
print(resp.json())

SpeechServiceUploadAndTranscribeResponse

{
  "file": { "id": "a1b2c3d4-...", "name": "meeting-recording", ... },
  "job": { "id": "d1e2f3a4-...", "status": "PENDING", ... },
  "summary": null
}

Create Transcription Job

POST /api/v1/speech-services/transcriptions

Requires Authentication - Scopes: speech:transcriptions:write; speech:translations:write when translations are requested

Rate Limited - Transcription admission, plus one Text Services execution and one Speech Services translation creation unit per target.

Submit a new transcription job for an existing uploaded file. The file must belong to the current user, must not be deleted, and must have completed ingestion (for URI imports).

SpeechServiceTranscriptionJobRequest

{
  "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transcription": {
    "model": "hebrew-general",
    "punctuation": true
  },
  "diarization": { "enabled": true, "mode": "SPEAKER" }
}

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/transcriptions \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transcription": {
      "model": "hebrew-general",
      "punctuation": true
    },
    "diarization": { "enabled": true }
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/speech-services/transcriptions",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transcription": {
            "model": "hebrew-general",
            "punctuation": True
        },
        "diarization": {"enabled": True}
    }
)
print(resp.json())

SpeechServiceTranscriptionJobResponse

Returns the created transcription job with status set to PENDING. See Data Types for the full response schema.

Automatic translations

Both Create Transcription Job and Upload and Transcribe accept translations. Every SpeechServiceTranslationOptions entry creates an independent translation job with status PENDING and phase WAITING_FOR_TRANSCRIPTION. The response's translationIds identifies the retained automatic children in request order (under job.translationIds for upload). List all translations through the paginated Translations API using transcriptionId.

Targets must be supported by the chosen Text Services alias. Omitted model resolves the tenant default and pins its concrete model name at submission. Duplicate target/model combinations and null entries are rejected with 400; the default maximum is 10 entries, configurable by koldan.speech-services.translation.max-automatic-targets. Each target requires speech:translations:write and consumes both translation rate limits at submission. An omitted child webhook inherits the parent webhook.

No monthly translation requests or tokens are reserved while waiting. When the transcript is ready, each child validates its source language pairs, retains an aligned source snapshot, and reserves Text Services request and translation-token quota. Unsupported pairs or exhausted quota fail only the affected child. Success commits usage once; failure or cancellation releases its reservation. Source failure fails waiting translations; cancellation propagates to active translation children. Each child has its own status, webhook and retention; one failure does not fail siblings or the transcription. See translation lifecycle and retention.

{
  "fileId": "dceecb24-6074-4c42-914e-c5974d8ad749",
  "transcription": { "model": "hebrew-general", "language": { "defaultLanguageCode": "he-IL" } },
  "translations": [
    { "targetLanguageCode": "en", "model": "translation-default" },
    { "targetLanguageCode": "ar", "model": "translation-default" }
  ]
}

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/transcriptions/upload \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -F "file=@meeting.wav" \
  -F "name=meeting" \
  -F 'transcription={"model":"hebrew-general"}' \
  -F 'translations=[{"targetLanguageCode":"en","model":"translation-default"}]'

Get Transcription Job

GET /api/v1/speech-services/transcriptions/{id}

Requires Authentication - Scopes: speech:transcriptions:read

Retrieve details of a specific transcription job including the full result when the job is completed and not purged.

Path Parameters

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

SpeechServiceTranscriptionJobResponse

Returns the full job object including the result field when status is COMPLETED and isPurged is false. See Data Types for the full response schema.

{
  "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "creationDate": "2026-04-01T10:00:00Z",
  "completionDate": "2026-04-01T10:05:32Z",
  "result": { "text": "Hello everyone...", "confidence": 0.94, ... },
  ...
}

Get Transcription Result

GET /api/v1/speech-services/transcriptions/{id}/result

Requires Authentication - Scopes: speech:transcriptions:read

Retrieve the transcription result for a completed job. The format parameter controls the export format.

Path Parameters

Query Parameters

curl -X GET "https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890/result?format=json" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}/result",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"format": "json"}
)
print(resp.json())

SpeechServiceTranscriptionJobResult

Returns the transcription result object. See Data Types for the full response schema.

{
  "text": "Hello everyone, welcome to the meeting...",
  "detectedLanguages": ["en"],
  "confidence": 0.94,
  "duration": 420.5,
  "segments": [
    { "start": 0.0, "end": 3.2, "text": "Hello everyone,", "speaker": "SPEAKER_00", ... }
  ]
}

Update Webhook

PUT /api/v1/speech-services/transcriptions/{id}/webhook

Requires Authentication - Scopes: speech:transcriptions:write

Set or update the webhook configuration for an existing transcription job. The job must not be in a terminal state (COMPLETED, FAILED, or CANCELLED).

Path Parameters

Request Body

{
  "url": "https://example.com/webhook/transcriptions",
  "secret": "whsec_abc123",
  "headers": { "X-Custom-Header": "my-value" },
  "includeSegments": true
}

curl -X PUT https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890/webhook \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook/transcriptions",
    "secret": "whsec_abc123"
  }'

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.put(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}/webhook",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com/webhook/transcriptions",
        "secret": "whsec_abc123"
    }
)
print(resp.json())

SpeechServiceTranscriptionJobResponse

Returns the updated job object. See Data Types for the full response schema.

Delete Webhook

DELETE /api/v1/speech-services/transcriptions/{id}/webhook

Requires Authentication - Scopes: speech:transcriptions:write

Remove the webhook configuration from an existing transcription job. The job must not be in a terminal state (COMPLETED, FAILED, or CANCELLED).

Path Parameters

curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890/webhook \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.delete(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}/webhook",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Webhook Events and Delivery

Koldan sends a JSON POST request when a configured transcription reaches COMPLETED, FAILED, or CANCELLED. A successful receiver must return any 2xx status code.

Webhook Payload

{
  "event": "transcription.completed",
  "jobId": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "timestamp": "2026-04-01T12:05:42Z",
  "result": {
    "text": "The completed transcript text.",
    "detectedLanguages": ["he"]
  },
  "errors": null
}

{
  "event": "transcription.completed",
  "jobId": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "timestamp": "2026-04-01T12:05:42Z",
  "result": {
    "text": "The completed transcript text.",
    "detectedLanguages": ["he"],
    "confidence": 0.95,
    "duration": 42.5,
    "segments": [
      {
        "start": 0.0,
        "end": 5.2,
        "text": "The completed transcript text.",
        "confidence": 0.95,
        "language": "he",
        "speaker": "SPEAKER_00",
        "words": [
          { "word": "The", "start": 0.0, "end": 0.3, "confidence": 0.98 },
          { "word": "completed", "start": 0.4, "end": 0.9, "confidence": 0.96 },
          { "word": "transcript", "start": 1.0, "end": 1.5, "confidence": 0.94 },
          { "word": "text.", "start": 1.6, "end": 2.0, "confidence": 0.92 }
        ]
      }
    ]
  },
  "errors": null
}

Delivery Headers

Verify X-Webhook-Signature against the raw body before parsing JSON, using a constant-time comparison. Custom headers from SpeechServiceWebhook are also included in the request.

Koldan retries timeouts, network failures, and non-2xx responses with configurable backoff. URL security violations are not retried. Because a response can be lost after your server processes it, receivers must safely handle duplicate deliveries.

For a complete signed receiver and optional cleanup flow, see Python SDK: Webhooks and Automatic Cleanup.

Cancel Job

POST /api/v1/speech-services/transcriptions/{id}/cancel

Requires Authentication - Scopes: speech:transcriptions:write

Cancel a pending or in-progress transcription job. Repeating cancellation for a CANCELLED job also waits for its remaining workflow cleanup; completed and failed jobs return 409.

Cancellation stops the transcription and its active automatic translations before returning 204. State changes and quota release are performed by their workflows. If cancellation has not completed within the request timeout, the API returns 503; retry using the same job ID. Cancelling a translation directly leaves its source transcription and other targets running.

Path Parameters

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890/cancel \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}/cancel",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Delete Job

DELETE /api/v1/speech-services/transcriptions/{id}

Requires Authentication - Scopes: speech:transcriptions:delete

Delete a transcription job. Only jobs in a terminal state (COMPLETED, FAILED, or CANCELLED) can be deleted. Use ?purge=true for immediate permanent removal of result and error data.

Path Parameters

Query Parameters

curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.delete(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Purge Job

POST /api/v1/speech-services/transcriptions/{id}/purge

Requires Authentication - Scopes: speech:transcriptions:delete

Permanently purge result and error data of a deleted transcription job. The job must already be deleted and not yet purged. This operation is irreversible.

Path Parameters

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/transcriptions/d1e2f3a4-b5c6-7890-abcd-ef1234567890/purge \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

job_id = "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/transcriptions/{job_id}/purge",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Data Types

SpeechServiceTranscriptionJobResponse

SpeechServiceTranscriptionJobResult

SpeechServiceTranscriptionSegment

SpeechServiceWordTiming

SpeechServiceTranslationOptions

One entry in the transcription request's translations array or upload's JSON translations part. Every entry creates one independent translation job.

Regional language codes remain in API metadata; the inference service receives only language subtags. Segments already in the target base language pass through without consuming translation tokens. A child with no segments requiring translation fails with NO_TRANSLATION_REQUIRED.

SpeechServiceTranscriptionOptions

SpeechServiceTranscriptionLanguageOptions

SpeechServiceDiarizationOptions

SpeechServiceChannelMapping

CommonWebhook

SpeechServiceWebhook

Extends CommonWebhook with speech-service-specific options.

SpeechServiceTranscriptionJobError

Enumerations

TranscriptionJobStatus

SpeechServiceDiarizationMode

TranscriptionErrorCode