Create Transcription Request

Endpoint Overview

Endpoint:
POST /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/transcriptionRequests

This endpoint creates a new transcription request to process one or more audio files. It supports a wide range of operations such as transcription, summarization, diarization, and classification.

The request is asynchronous. Once accepted, you receive a process_cuid to track the process and its actions. You can check the status using the dedicated result endpoint.

---

Request Body

The request body must be sent as multipart/form-data and includes a list of signed URLs of audio files, actions to perform, and optional parameters such as vocabulary, external reference, and TTL.

Field	Description	Type	Required	Example
audio_files	List of URLs pointing to audio files to upload. None if process_cuid set (audios uploaded via our API).	Array	Yes	[ "https://storage.googleapis.com/my-bucket/my-audio.mp3" ]
process_cuid	process cuid returned by GET /signedUrl, if audios already uploaded in our server (None if audio_files set).	String	Yes	[ "https://storage.googleapis.com/my-bucket/my-audio.mp3" ]
actions	List of actions to perform on the transcription request.	Array	Yes	See below for details
vocabulary	Optional list of custom words to improve transcription accuracy.	Array	No	[ "DalirSicx", "metAl Plus" ]
ttl	Time in minutes to keep the session alive after the last action (default: 0).	Integer	No	0
external_ref	Optional external ID to track the request.	String	No	"1234-abcd-56ef-7891"

Action Object Format

Each action in the actions array includes the following fields:

Field	Description	Type	Required
action_type	Type of operation. One of: transcription, factual_summary, detailed_summary, technical_summary.	String	Yes
webhook	Webhook configuration to notify client upon completion (optional).	Object	Yes
webhook.url	Webhook URL to send the result to (optional).	String	Yes
webhook.headers	Optional HTTP headers (e.g., Authorization tokens) to include in webhook requests.	Object	No
webhook.external_metadata	Optional metadata for tracking and context (optional).	Object	No

---

Example Request

{
  "audio_files": ["https://storage.googleapis.com/my-bucket/audio-123.mp3"],
  "actions": [
    {
      "action_type": "factual_summary",
      "webhook": {
        "url": "https://client-webhook.example.com/receive-summary",
        "headers": { "access_token": "abc123xyz" },
        "external_metadata": {
          "conversation_id": "conv-789",
          "source": "crm-system",
          "status": "new"
        }
      }
    }
  ],
  "vocabulary": ["DalirSicx", "metAl Plus"],
  "ttl": 0,
  "external_ref": "1234-abcd-56ef-7891"
}

OR

{
  "process_cuid": "abcd1234",
  "actions": [
    {
      "action_type": "factual_summary",
      "webhook": {
        "url": "https://client-webhook.example.com/receive-summary",
        "headers": { "access_token": "abc123xyz" },
        "external_metadata": {
          "conversation_id": "conv-789",
          "source": "crm-system",
          "status": "new"
        }
      }
    }
  ],
  "vocabulary": ["DalirSicx", "metAl Plus"],
  "ttl": 0,
  "external_ref": "1234-abcd-56ef-7891"
}

Response

If successful, the API responds with a 202 Accepted status and a JSON body containing a unique process_cuid.

Field	Description	Type	Example
process_cuid	Unique process identifier	String	"123e4567e89b"
message	Acknowledgment message from the API	String	"Your request has been acknowledged by our services."

Example Response

{
  "process_cuid": "123e4567e89b",
  "message": "Your request has been acknowledged by our services."
}