> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.cloudraker.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server. # Create a realtime transcription POST https://api.cloudraker.com/v1/realtime/transcriptions Content-Type: application/json Creates a live transcription session and returns a `websocket.url` for one client. Call this from your backend with your API key. Give `websocket.url` to the browser (or any client). The URL carries a single-use ticket that expires after 60 seconds. The client opens the socket and sends raw PCM16 little-endian audio, 16 kHz, mono, as binary frames. The session sends back `partial` and `final` text. The WebSocket upgrade is not an API operation: it is documented on the capability page, not here. Use `POST /v1/realtime/transcriptions/{id}/tickets` to get a new ticket for a reconnect. **Pricing.** A 5-credit session fee, charged when the first decoder joins, or when a session that no client connected to expires. Then 2 credits per started minute of decoded audio. When the session fails on our side (no capacity, no decoder), you pay nothing. With `finalPass: true`, the batch diarized transcription is billed by the normal audio meters on top (20 credits per minute, minimum 1 minute). **Data.** Montreal decode, North America session state, the final pass may run in the US; no residency guarantee. The server keeps no transcript: persist the finals your client receives. Without `finalPass`, no audio is kept after close. **Limits.** A session lasts at most 4 hours (2 hours with `finalPass`). It closes after 5 minutes without audio. It expires when no client connects within 10 minutes. A revoked API key does not end its live sessions. MCP code mode can create a session, but it cannot stream audio. Send an `idempotency-key`: a retry with the same key and body returns the same session with a fresh ticket and the `idempotent-replay: true` header. **Learn more:** [Realtime transcription](https://docs.cloudraker.com/capabilities/realtime-transcription) Reference: https://docs.cloudraker.com/paperwork/api/realtime-transcriptions/create-realtime-transcription ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `idempotency-key` (string, optional) — A retry with the same key and body returns the same session. ### Body (application/json) This endpoint expects a CreateRealtimeTranscriptionBody. - `finalPass` (boolean, optional, default: false) — Archive the audio as a file and run batch diarized transcription at close. Billed by the normal audio meters (minimum 1 diarized minute). - `maxDurationSeconds` (integer, optional) — Hard cap on received audio. Default and max 14400 (4 h); default and max 7200 with finalPass. - `metadata` (map from string to string, optional) — Kept 30 days after close. Do not put personal data here. ## Response ### 201 The session, with `websocket` for the first client. - `object` ("realtime_transcription", required) - `id` (string, required) - `status` (enum, required) - Allowed values: `created`, `active`, `closing`, `closed`, `expired`, `failed` - `closeReason` (enum, required, nullable) - Allowed values: `client_end`, `stopped`, `idle_timeout`, `max_duration`, `credits_exhausted`, `worker_unavailable`, `too_fast`, `internal_error` - `audio` (RealtimeTranscriptionAudio, required) - `maxDurationSeconds` (integer, required) - `audioSeconds` (double, required) — Received audio, in seconds. - `billedMinutes` (integer, required) — Minutes charged so far. - `finalPass` (RealtimeTranscriptionFinalPass, required) - `metadata` (map from string to string, required, nullable) - `createdAt` (datetime, required) - `connectedAt` (datetime, required, nullable) - `closedAt` (datetime, required, nullable) - `connectBy` (datetime, required, nullable) — Connect before this time, or the session expires. Null once a client connected. - `websocket` (RealtimeTranscriptionTicket, optional) — Only in the create response. ## Errors ### 400 Bad Request Error `invalid_request` — the body failed validation. - `any` ### 401 Unauthorized Error Missing or invalid credential. - `any` ### 402 Payment Required Error `credits_exhausted`, or `feature_not_in_plan` — your plan does not include realtime transcription. - `any` ### 403 Forbidden Error The credential may not use the /v1 API. - `any` ### 409 Conflict Error `idempotency_conflict` — the key was used with another body. - `any` ### 429 Too Many Requests Error Rate limited. The `/v1` API allows at least **67 requests per minute per organization** (about 1,000 requests per 15 minutes) — a guaranteed floor, enforced per edge location, so a geographically spread caller may get more. Wait for the `Retry-After` interval and retry — the error is `retryable`. - `code` (enum, required) - Allowed values: `rate_limited` - `message` (string, required) - `retryable` (boolean, required) - `requestId` (string, required) - `docUrl` (string, optional) ### 503 Service Unavailable Error `capacity_unavailable` — no capacity is free. Nothing was charged. Retry. - `any` ## Types ### RealtimeTranscriptionAudio - `encoding` ("pcm_s16le", required) - `sampleRate` (double, required) - `channels` (double, required) ### RealtimeTranscriptionFinalPass - `enabled` (boolean, required) - `status` (enum, required) - Allowed values: `disabled`, `recording`, `uploading`, `processing`, `ready`, `failed`, `skipped` - `fileId` (string, required, nullable) — A normal /v1 file (`GET /v1/files/{id}`). ### RealtimeTranscriptionTicket Only in the create response. - `object` ("realtime_transcription_ticket", required) - `url` (string, required) — The `wss://` URL to open. It carries a single-use ticket that expires after 60 seconds. - `expiresAt` (datetime, required) ## Examples **Request** ```json {} ``` **Response** ```json { "object": "string", "id": "rtt_01KZ0000000000000000000000", "status": "created", "closeReason": "client_end", "audio": { "encoding": "string", "sampleRate": 1.1, "channels": 1.1 }, "maxDurationSeconds": 1, "audioSeconds": 1.1, "billedMinutes": 1, "finalPass": { "enabled": true, "status": "disabled", "fileId": "string" }, "metadata": {}, "createdAt": "2024-01-15T09:30:00Z", "connectedAt": "2024-01-15T09:30:00Z", "closedAt": "2024-01-15T09:30:00Z", "connectBy": "2024-01-15T09:30:00Z", "websocket": { "object": "string", "url": "string", "expiresAt": "2024-01-15T09:30:00Z" } } ``` **SDK Code** ```typescript import { CloudRakerClient } from "@cloudraker/api"; async function main() { const client = new CloudRakerClient({ token: "YOUR_TOKEN_HERE", }); await client.realtimeTranscriptions.createRealtimeTranscription({}); } main(); ``` ```python from cloudraker import CloudRaker client = CloudRaker( token="YOUR_TOKEN_HERE", ) client.realtime_transcriptions.create_realtime_transcription() ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.cloudraker.com/v1/realtime/transcriptions" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.cloudraker.com/v1/realtime/transcriptions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.cloudraker.com/v1/realtime/transcriptions") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://api.cloudraker.com/v1/realtime/transcriptions', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.cloudraker.com/v1/realtime/transcriptions"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.cloudraker.com/v1/realtime/transcriptions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```