Speech is Cheap

https://docs.speechischeap.com/
Admin
Speech is Cheap is an API service that allows users to create, manage, and retrieve the status and...
Tokens:8,901
Snippets:45
Trust Score:5.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Error Response Example

Source: https://docs.speechischeap.com/jobs-v2/read

This example shows an HTTP error response returned when a server-side error occurs during the job status request. The status code is 500 Internal Server Error.

```http
HTTP/1.1 500 Internal Server Error  
  
  
Internal Server Error
```

--------------------------------

### Error Response HTTP

Source: https://docs.speechischeap.com/jobs-v1/read

This example shows an error response from the API, indicating a server-side issue (500 Internal Server Error) potentially related to downloading output.

```http
HTTP/1.1 500 Internal Server Error
  
  
Error downloading the output
```

--------------------------------

### GET /v2/jobs/auth

Source: https://docs.speechischeap.com/jobs-v2/changelog

This endpoint is used to test the authentication mechanism for the v2 API.

```APIDOC
## GET /v2/jobs/auth

### Description
Tests the authentication for the v2 API endpoints.

### Method
GET

### Endpoint
/v2/jobs/auth

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **status** (string) - Indicates if authentication is successful.

#### Response Example
```json
{
  "status": "authenticated"
}
```
```

--------------------------------

### GET /health

Source: https://docs.speechischeap.com/jobs-v2

Check the health of the Speech is Cheap Jobs API.

```APIDOC
## GET /health

### Description
This endpoint allows you to check the health of the Speech is Cheap Jobs API.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the API (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Get Job Status and Output using cURL

Source: https://docs.speechischeap.com/jobs-v2/read

This snippet demonstrates how to request the status and output of a specific transcription job using the cURL command-line tool. It requires the job ID to be appended to the API endpoint.

```bash
curl https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic
```

--------------------------------

### Check Job Status and Output with cURL

Source: https://docs.speechischeap.com/jobs-v1/read

This example demonstrates how to check the status and retrieve the output of a specific transcription job using cURL. It requires the job ID and an API key for authentication.

```shell
curl --request GET \
     --url https://api.speechischeap.com/v1/jobs/00000000-1111-4222-3333-444444444444-u1 \
     --header 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### GET /v2/jobs/:job_id

Source: https://docs.speechischeap.com/jobs-v2/read

This endpoint allows you to check the status of an existing transcription job and retrieve its results if available.

```APIDOC
## GET /v2/jobs/:job_id

### Description
This endpoint allows you to check the status of an existing transcription job and retrieve its results if available.

### Method
GET

### Endpoint
`https://api.speechischeap.com/v2/jobs/:job_id`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the transcription job.

### Request Example
#### Using cURL
```bash
curl https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the job.
- **output** (object) - The transcription results or an empty object if pending.
- **status** (string) - The current status of the job (e.g., PENDING, COMPLETED, CANCELED).

#### Pending Job Response
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "PENDING"
}
```

#### Completed Job Response
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "segments": [
      {
        "end": 12.345,
        "id": 1,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

#### Canceled Job Response
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "CANCELED"
}
```

#### Error Response (500)
```json
{
  "error": "Internal Server Error"
}
```
```

--------------------------------

### Create Transcription Job using cURL

Source: https://docs.speechischeap.com/jobs-v2/create

Example of creating a new transcription job using cURL. This command sends a POST request to the API endpoint with necessary headers and a JSON payload containing the audio file URL and webhook URL.

```bash
curl --request POST \
     --url https://api.speechischeap.com/v2/jobs/ \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{ \
       "input_url": "https://example.com/audio-file.mp3", \
       "webhook_url": "https://your-domain.com/webhook" \
     }'
```

--------------------------------

### GET /v2/jobs/health

Source: https://docs.speechischeap.com/jobs-v2/changelog

This endpoint checks the health status of the v2 service.

```APIDOC
## GET /v2/jobs/health

### Description
Checks the health of the v2 service.

### Method
GET

### Endpoint
/v2/jobs/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service.

#### Response Example
```json
{
  "status": "healthy"
}
```
```

--------------------------------

### Full Transcription Job Request Body JSON

Source: https://docs.speechischeap.com/jobs-v1/create

An example JSON object for the request body, demonstrating how to include all optional parameters for creating a transcription job. This allows for advanced configuration such as word-level timing, hotwords, multilingual detection, and segment duration.

```json
{
  "can_parse_words": true,
  "hotwords": "AI, ML, Neural Networks",
  "input_url": "https://example.com/audio-file.mp3",
  "language": "en",
  "prompt": "This is a technical discussion about artificial intelligence",
  "segment_duration": 15,
  "webhook_url": "https://your-domain.com/webhook"
}
```

--------------------------------

### Label Audio JSON Response

Source: https://docs.speechischeap.com/jobs-v2/create

Returns a JSON object with an audio classification 'label' for each segment. This feature categorizes segments, for example, identifying 'music'.

```json
{
  "label": "music"
}
```

--------------------------------

### Create Transcription Job using cURL

Source: https://docs.speechischeap.com/jobs-v1/create

Example of creating a new transcription job using cURL. This command sends a POST request to the API endpoint with necessary headers and a basic JSON payload containing the audio file URL.

```bash
curl --request POST \
     --url https://api.speechischeap.com/v1/jobs/ \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{ "input_url": "https://example.com/audio-file.mp3" }'
```

--------------------------------

### GET /v1/jobs/:job_id

Source: https://docs.speechischeap.com/jobs-v1/read

Retrieves the status and output of a specific transcription job. Authentication is required via a Bearer token.

```APIDOC
## GET /v1/jobs/:job_id

### Description
This endpoint allows you to check the status of an existing transcription job and retrieve its results if available.

### Method
GET

### Endpoint
`https://api.speechischeap.com/v1/jobs/:job_id`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the transcription job.

#### Query Parameters
None

#### Request Body
None

### Authentication
Requires authentication using a Bearer token in the HTTP header:
`Authorization: Bearer YOUR_API_KEY`

### Request Example
```curl
curl --request GET \
     --url https://api.speechischeap.com/v1/jobs/00000000-1111-4222-3333-444444444444-u1 \
     --header 'Authorization: Bearer YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **id** (string) - The job ID.
- **output** (object) - The transcription output or error details.
- **status** (string) - The current status of the job (e.g., PENDING, COMPLETED, CANCELED, UNKNOWN).

#### Pending Job Response Example
```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {},
  "status": "PENDING"
}
```

#### Completed Job Response Example
```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "segments": [
      {
        "end": 12.345,
        "id": 1,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

#### Failed Job Response Example
```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "error": "Some error message"
  },
  "status": "COMPLETED"
}
```

#### Error Response Example
```
HTTP/1.1 500 Internal Server Error

Error downloading the output
```

### Error Handling
- **401 Unauthorized**: Invalid or missing authentication token.
- **404 Not Found**: Job not found.
- **500 Internal Server Error**: Server-side error occurred.
```

--------------------------------

### Parse Words JSON Response

Source: https://docs.speechischeap.com/jobs-v2/create

Returns a JSON object containing an array of 'words'. Each word object includes 'start' and 'end' timestamps and the 'text' content. This provides granular word-level information within each audio segment.

```json
{
  "words": [
    {
      "start": 2.345,
      "end": 2.567,
      "text": "hi"
    }
  ]
}
```

--------------------------------

### GET /v2/jobs/:job_id

Source: https://docs.speechischeap.com/jobs-v2/changelog

Retrieves the status and details of a specific job. Note: Attempting to download unsuccessful transcriptions via this endpoint will result in a 404 Not Found.

```APIDOC
## GET /v2/jobs/:job_id

### Description
Retrieves the status and details of a specific job. Note: Attempting to download unsuccessful transcriptions via this endpoint will result in a 404 Not Found.

### Method
GET

### Endpoint
/v2/jobs/:job_id

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier for the job.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body for GET request)

### Response
#### Success Response (202)
- **job_id** (string) - The unique identifier for the job.
- **status** (string) - The current status of the job (e.g., "PROCESSING", "COMPLETED", "FAILED").
- **input_url** (string) - The URL of the input audio file.
- **webhook_url** (string) - The URL to which callback notifications will be sent.

#### Response Example
```json
{
  "job_id": "-sic",
  "status": "COMPLETED",
  "input_url": "http://example.com/audio.mp3",
  "webhook_url": "http://example.com/webhook"
}
```
```

--------------------------------

### Get Job Status and Output

Source: https://docs.speechischeap.com/jobs-v1

Retrieves the current status of a transcription job and its output if the job is completed. Requires the job ID.

```APIDOC
## GET /jobs/{job_id}

### Description
This endpoint allows you to check the status of an existing transcription job and retrieve its results if available.

### Method
GET

### Endpoint
/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the transcription job.

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier of the transcription job.
- **status** (string) - The current status of the job (e.g., "processing", "completed", "failed").
- **result** (object) - The transcription result, available only if the status is "completed".
  - **text** (string) - The transcribed text.

#### Response Example
```json
{
  "job_id": "abc123xyz789",
  "status": "completed",
  "result": {
    "text": "This is the transcribed text."
  }
}
```
```

--------------------------------

### GET /jobs/{job_id}

Source: https://docs.speechischeap.com/jobs-v2

Check the status of an existing transcription job and retrieve its results if available.

```APIDOC
## GET /jobs/{job_id}

### Description
This endpoint allows you to check the status of an existing transcription job and retrieve its results if available.

### Method
GET

### Endpoint
/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job to retrieve.

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier of the job.
- **status** (string) - The current status of the job (e.g., "processing", "completed", "failed").
- **result_url** (string) - The URL to the transcription results, if the job is completed.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "completed",
  "result_url": "https://example.com/results/a1b2c3d4-e5f6-7890-1234-567890abcdef.json"
}
```
```

--------------------------------

### Transcription Job Error Response

Source: https://docs.speechischeap.com/jobs-v1/create

An example of an error response when a transcription job creation fails due to invalid parameters. This indicates a 'Bad Request' with a specific error message.

```http
HTTP/1.1 400 Bad Request


Missing required "input_url" parameter
```

--------------------------------

### Canceled Job Response Structure

Source: https://docs.speechischeap.com/jobs-v2/read

This JSON structure indicates that a transcription job was canceled. The 'status' field will be 'CANCELED', and the 'output' field will be empty.

```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "CANCELED"
}
```

--------------------------------

### Failed Job Response JSON

Source: https://docs.speechischeap.com/jobs-v1/read

This JSON structure represents the response when a transcription job has failed. It includes the job ID, an output object with an error message, and the status.

```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "error": "Some error message"
  },
  "status": "COMPLETED"
}
```

--------------------------------

### Pending Job Response Structure

Source: https://docs.speechischeap.com/jobs-v2/read

This JSON structure represents the response when a transcription job is still in progress. The 'status' field is set to 'PENDING', and the 'output' field is an empty object, indicating no results are available yet.

```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "PENDING"
}
```

--------------------------------

### Completed Job Response Structure

Source: https://docs.speechischeap.com/jobs-v2/read

This JSON structure shows the response for a successfully completed transcription job. The 'status' field is 'COMPLETED', and the 'output' field contains the detailed transcription results, including segments and text.

```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "segments": [
      {
        "end": 12.345,
        "id": 1,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

--------------------------------

### Completed Job Response JSON

Source: https://docs.speechischeap.com/jobs-v1/read

This JSON structure represents the response when a transcription job has successfully COMPLETED. It includes the job ID, the transcribed output with segments, and the status.

```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "segments": [
      {
        "end": 12.345,
        "id": 1,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

--------------------------------

### Pending Job Response JSON

Source: https://docs.speechischeap.com/jobs-v1/read

This JSON structure represents the response when a transcription job is still in the PENDING state. It includes the job ID and an empty output field.

```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {},
  "status": "PENDING"
}
```

--------------------------------

### POST /jobs

Source: https://docs.speechischeap.com/jobs-v2

Create a new transcription job by providing an audio file URL, a webhook callback URL, and optional configuration parameters.

```APIDOC
## POST /jobs

### Description
This endpoint allows you to create a new transcription job by providing an audio file URL, a webhook callback URL, and optional configuration parameters.

### Method
POST

### Endpoint
/jobs

### Parameters
#### Request Body
- **audio_url** (string) - Required - The URL of the audio file to transcribe.
- **callback_url** (string) - Required - The URL to send job completion notifications to.
- **config** (object) - Optional - Configuration options for the transcription.
  - **language** (string) - Optional - The language of the audio.
  - **output_format** (string) - Optional - The desired output format for the transcription.

### Request Example
```json
{
  "audio_url": "https://example.com/audio.mp3",
  "callback_url": "https://example.com/webhook",
  "config": {
    "language": "en-US",
    "output_format": "json"
  }
}
```

### Response
#### Success Response (201)
- **job_id** (string) - The unique identifier for the created job.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### POST /v2/jobs/

Source: https://docs.speechischeap.com/jobs-v2/create

Creates a new transcription job by providing an audio file URL and an optional webhook URL. Supports various configuration parameters to customize the transcription process.

```APIDOC
## POST /v2/jobs/

### Description
Creates a new transcription job by providing an audio file URL and an optional webhook URL. Supports various configuration parameters to customize the transcription process.

### Method
POST

### Endpoint
https://api.speechischeap.com/v2/jobs/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input_url** (string) - Required - The URL of the audio file to transcribe. Must be between six seconds and 24 hours long.
- **webhook_url** (string) - Optional - The URL where the transcription results may be sent to via a POST request.
- **can_label_audio** (boolean) - Optional - When enabled, includes an audio classification label in the transcription. Defaults to `false`.
- **can_parse_speakers** (boolean) - Optional - When enabled, adds `speaker_id` to each segment based on the speaker's voice. Defaults to `false`.
- **can_parse_words** (boolean) - Optional - When enabled, includes a timecode for every word in the transcription. Defaults to `false`.
- **hotwords** (string) - Optional - Specific words or phrases to help improve transcription accuracy. Defaults to `""`.
- **is_private** (boolean) - Optional - When enabled, redacts the original `input_url` for privacy. Defaults to `false`.
- **language** (string) - Optional - Two-letter ISO 639-1 language code (e.g., "en"). If not provided, the language will be auto-detected from the first segment. Defaults to `""`.
- **minimum_confidence** (number) - Optional - Filter out segments that fall below this confidence threshold. Applies both to transcriptions and to non-speech audio labels when `can_label_audio` is `true`. Defaults to `0.5`.
- **prompt** (string) - Optional - Custom prompt to adjust transcription style. Should match the audio language. Defaults to `""`.
- **segment_duration** (number) - Optional - Duration of each transcription segment in seconds. Must be between six and 30 seconds. Defaults to `30`.
- **user_agent** (string) - Optional - Custom user agent header to fetch the audio file. Defaults to internal value.

### Request Example
#### Using cURL
```curl
curl --request POST \
     --url https://api.speechischeap.com/v2/jobs/ \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{  
       "input_url": "https://example.com/audio-file.mp3",  
       "webhook_url": "https://your-domain.com/webhook"  
     }'
```

#### Including all optional parameters
```json
{
  "input_url": "https://example.com/audio-file.mp3",
  "webhook_url": "https://your-domain.com/webhook",
  "can_label_audio": true,
  "can_parse_speakers": true,
  "can_parse_words": true,
  "hotwords": "AI, ML, Neural Networks",
  "language": "en",
  "minimum_confidence": 0,
  "prompt": "This is a technical discussion about artificial intelligence",
  "segment_duration": 15
}
```

### Response
#### Success Response (202 Accepted)
- **id** (string) - The unique identifier for the transcription job.
- **output** (object) - An empty object for synchronous responses.
- **status** (string) - The status of the job, e.g., "PENDING".

#### Response Example
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "PENDING"
}
```

#### Error Responses
- **400 Bad Request**: Missing or invalid parameters.
- **401 Unauthorized**: Invalid or missing authentication token.
- **500 Internal Server Error**: Server-side error occurred.

#### Error Response Example
```
HTTP/1.1 400 Bad Request

Missing required "input_url" parameter
```

### Webhook Responses
#### Success (COMPLETED)
- **id** (string) - The unique identifier for the transcription job.
- **output** (object) - Contains transcription segments.
  - **segments** (array) - An array of transcription segments.
    - **confidence** (number) - The confidence score for the segment.
    - **end** (number) - The end time of the segment in seconds.
    - **id** (integer) - The segment ID.
    - **language** (string) - The detected language of the segment.
    - **processing_duration_in_s** (number) - The processing duration in seconds.
    - **seek** (number) - The seek time for the segment.
    - **start** (number) - The start time of the segment in seconds.
    - **text** (string) - The transcribed text for the segment.
    - **words** (null or array) - Word-level details if `can_parse_words` is enabled.
- **status** (string) - "COMPLETED".

#### Success Response Example
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "segments": [
      {
        "confidence": 0.987,
        "end": 12.345,
        "id": 1,
        "language": "en (99.95%)",
        "processing_duration_in_s": 0.321,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

#### Failure (FAILED)
- **id** (string) - The unique identifier for the transcription job.
- **output** (object) - Contains error details.
  - **error** (string) - A message describing the failure.
- **status** (string) - "FAILED".

#### Failure Response Example
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "error": "Some error message"
  },
  "status": "FAILED"
}
```

#### Cancelation (CANCELED)
- **id** (string) - The unique identifier for the transcription job.
- **output** (object) - An empty object.
- **status** (string) - "CANCELED".

#### Cancelation Response Example
```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {},
  "status": "CANCELED"
}
```
```

--------------------------------

### Transcription Job Creation Request Body

Source: https://docs.speechischeap.com/jobs-v2/create

JSON object representing the request body for creating a transcription job. This includes the required `input_url` and `webhook_url`, along with optional parameters to customize transcription, such as enabling speaker diarization, word timestamps, and language detection.

```json
{
  "input_url": "https://example.com/audio-file.mp3",
  "webhook_url": "https://your-domain.com/webhook",
  "can_label_audio": true,
  "can_parse_speakers": true,
  "can_parse_words": true,
  "hotwords": "AI, ML, Neural Networks",
  "language": "en",
  "minimum_confidence": 0,
  "prompt": "This is a technical discussion about artificial intelligence",
  "segment_duration": 15
}
```

--------------------------------

### Create a New Transcription Job

Source: https://docs.speechischeap.com/jobs-v1

Creates a new transcription job. You need to provide the URL of the audio file to transcribe. Optionally, you can specify a webhook URL for notifications and other configuration settings.

```APIDOC
## POST /jobs

### Description
This endpoint allows you to create a new transcription job by providing an audio file URL and optionally a webhook callback URL plus additional configuration parameters.

### Method
POST

### Endpoint
/jobs

### Parameters
#### Query Parameters
- **audio_url** (string) - Required - The URL of the audio file to transcribe.
- **webhook_url** (string) - Optional - The URL to send job completion notifications to.

#### Request Body
- **config** (object) - Optional - Additional configuration parameters for the transcription.
  - **language** (string) - Optional - The language of the audio. (e.g., "en", "es")
  - **encoding** (string) - Optional - The encoding of the audio. (e.g., "wav", "mp3")

### Request Example
```json
{
  "audio_url": "https://example.com/audio.wav",
  "webhook_url": "https://example.com/webhook",
  "config": {
    "language": "en",
    "encoding": "wav"
  }
}
```

### Response
#### Success Response (201)
- **job_id** (string) - The unique identifier for the created transcription job.

#### Response Example
```json
{
  "job_id": "abc123xyz789"
}
```
```

--------------------------------

### POST /v1/jobs/

Source: https://docs.speechischeap.com/jobs-v1/create

Creates a new transcription job. You must provide a URL to an audio file. You can also specify a webhook URL to receive transcription results asynchronously, along with other optional configuration parameters.

```APIDOC
## POST /v1/jobs/

### Description
Creates a new transcription job by providing an audio file URL and optionally a webhook callback URL plus additional configuration parameters.

### Method
POST

### Endpoint
https://api.speechischeap.com/v1/jobs/

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **input_url** (string) - Required - The URL of the audio file to transcribe.
- **can_parse_words** (boolean) - Optional - Defaults to `false`. When enabled, includes a timecode for every word in the transcription.
- **hotwords** (string) - Optional - Specific words or phrases to help improve transcription accuracy.
- **is_multilingual** (boolean) - Optional - Defaults to `false`. When enabled, language will be auto-detected in each segment.
- **language** (string) - Optional - Two-letter ISO 639-1 language code (e.g., "en"). If not provided, the language will be auto-detected from the first segment. Ignored if `is_multilingual` is enabled.
- **prompt** (string) - Optional - Custom prompt to adjust transcription style. Should match the audio language.
- **segment_duration** (number) - Optional - Defaults to `30`. Duration of each transcription segment in seconds.
- **webhook_url** (string) - Optional - The URL where the transcription results will be sent via a POST request.

### Request Example
#### cURL
```bash
curl --request POST \
     --url https://api.speechischeap.com/v1/jobs/ \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{ "input_url": "https://example.com/audio-file.mp3" }'
```

#### Full Parameters JSON
```json
{
  "can_parse_words": true,
  "hotwords": "AI, ML, Neural Networks",
  "input_url": "https://example.com/audio-file.mp3",
  "language": "en",
  "prompt": "This is a technical discussion about artificial intelligence",
  "segment_duration": 15,
  "webhook_url": "https://your-domain.com/webhook"
}
```

### Response
#### Success Response (201 Created)
Returns the job ID, an empty output object, and the initial status.
```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {},
  "status": "PENDING"
}
```

#### Error Response (400 Bad Request)
Indicates missing or invalid parameters.
```json
{
  "error": "Missing required \"input_url\" parameter"
}
```

#### Error Response (401 Unauthorized)
Indicates an invalid or missing authentication token.

#### Error Response (500 Internal Server Error)
Indicates a server-side error occurred.
```

--------------------------------

### Asynchronous Success Webhook Response

Source: https://docs.speechischeap.com/jobs-v2/create

The webhook payload received upon successful completion of a transcription job. It includes the job ID, detailed output with segments (including text, confidence, start/end times), and a COMPLETED status.

```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "segments": [
      {
        "confidence": 0.987,
        "end": 12.345,
        "id": 1,
        "language": "en (99.95%)",
        "processing_duration_in_s": 0.321,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

--------------------------------

### Webhook Responses

Source: https://docs.speechischeap.com/jobs-v1/create

Handles asynchronous responses sent to the specified webhook URL upon job completion or failure.

```APIDOC
## Webhook Responses

### Success Response
When a transcription job is completed successfully, the webhook will receive a POST request with the following structure:

```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "segments": [
      {
        "end": 12.345,
        "id": 1,
        "seek": 1234.5,
        "start": 1.234,
        "text": "This is an example of some transcribed text output.",
        "words": null
      }
    ]
  },
  "status": "COMPLETED"
}
```

### Failure Response
If the job fails during processing, the webhook will receive an error response:

```json
{
  "id": "00000000-1111-4222-3333-444444444444-u1",
  "output": {
    "error": "Some error message"
  },
  "status": "COMPLETED" 
}
```
```

--------------------------------

### Asynchronous Failure Webhook Response

Source: https://docs.speechischeap.com/jobs-v2/create

The webhook payload received when a transcription job fails. It contains the job ID, an output object with an error message, and a FAILED status.

```json
{
  "id": "00000000-1111-7222-b333-444444444444-sic",
  "output": {
    "error": "Some error message"
  },
  "status": "FAILED"
}
```

--------------------------------

### Parse Speakers JSON Response

Source: https://docs.speechischeap.com/jobs-v2/create

Returns a JSON object with a 'speaker_id' for each speech segment. This is useful for identifying different speakers in an audio file. The 'speaker_id' may be an empty string if speech is not detected in a segment, especially when used with the Label Audio add-on.

```json
{
  "speaker_id": "A"
}
```

--------------------------------

### DELETE /jobs/{job_id}

Source: https://docs.speechischeap.com/jobs-v2

Cancel a pending transcription job.

```APIDOC
## DELETE /jobs/{job_id}

### Description
This endpoint allows you to cancel a pending transcription job.

### Method
DELETE

### Endpoint
/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job to cancel.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the job has been cancelled.

#### Response Example
```json
{
  "message": "Job a1b2c3d4-e5f6-7890-1234-567890abcdef has been cancelled."
}
```
```

--------------------------------

### Cancel Pending Job using cURL

Source: https://docs.speechischeap.com/jobs-v1/delete

This snippet demonstrates how to cancel a pending transcription job using the cURL command-line tool. It requires the job ID and an API key for authentication. The job, once canceled, cannot be resumed.

```bash
curl --request DELETE \
     --url https://api.speechischeap.com/v1/jobs/00000000-1111-4222-3333-444444444444-u1 \
     --header 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Cancel Job Request - cURL

Source: https://docs.speechischeap.com/jobs-v2/delete

This snippet demonstrates how to cancel a pending transcription job using cURL. It requires the job ID and an API key for authentication. The request sends a DELETE request to the specified endpoint.

```bash
curl --request DELETE \
     --url https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic \
     --header 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### DELETE /v2/jobs/:job_id

Source: https://docs.speechischeap.com/jobs-v2/delete

Cancels a pending transcription job. Authentication is required.

```APIDOC
## DELETE /v2/jobs/:job_id

### Description
This endpoint allows you to cancel a pending transcription job.

### Method
DELETE

### Endpoint
https://api.speechischeap.com/v2/jobs/:job_id

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job to cancel.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "language": "APIDOC",
  "code": "curl --request DELETE \n     --url https://api.speechischeap.com/v2/jobs/00000000-1111-7222-b333-444444444444-sic \n     --header 'Authorization: Bearer YOUR_API_KEY'"
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Indicates the job was successfully canceled.

#### Response Example
```json
{
  "language": "APIDOC",
  "code": "HTTP/1.1 200 OK\n\nOK"
}
```

#### Error Response (401 Unauthorized)
- **message** (string) - Indicates an invalid or missing authentication token.

#### Error Response (404 Not Found)
- **message** (string) - Indicates the job was not found, already completed, or already canceled.

#### Error Response (500 Internal Server Error)
- **message** (string) - Indicates a server-side error occurred.

### Note
Attempting to cancel completed, failed, or previously-canceled jobs will return 404 Not Found.
```

--------------------------------

### Cancel a Pending Job

Source: https://docs.speechischeap.com/jobs-v1

Cancels a transcription job that is currently pending. Once canceled, the job cannot be resumed or its results retrieved.

```APIDOC
## DELETE /jobs/{job_id}

### Description
This endpoint allows you to cancel a pending transcription job. Once canceled, the job cannot be resumed or retrieved.

### Method
DELETE

### Endpoint
/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the transcription job to cancel.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the job was canceled.

#### Response Example
```json
{
  "message": "Job abc123xyz789 has been successfully canceled."
}
```
```

--------------------------------

### Cancel a Pending Job

Source: https://docs.speechischeap.com/jobs-v1/delete

This endpoint allows you to cancel a pending transcription job. Once canceled, the job cannot be resumed or retrieved.

```APIDOC
## DELETE /v1/jobs/:job_id

### Description
Allows cancellation of a pending transcription job. Canceled jobs cannot be resumed or retrieved.

### Method
DELETE

### Endpoint
`/v1/jobs/:job_id`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job to cancel.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
```json
{
  "curl": "curl --request DELETE \ \
       --url https://api.speechischeap.com/v1/jobs/00000000-1111-4222-3333-444444444444-u1 \ \
       --header 'Authorization: Bearer YOUR_API_KEY'"
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Indicates the job was successfully canceled.

#### Response Example
```json
{
  "status": "OK",
  "message": "OK"
}
```

#### Error Responses
- **401 Unauthorized**: Invalid or missing authentication token.
- **404 Not Found**: Job not found, already completed, or already canceled.
- **500 Internal Server Error**: Server-side error occurred.

#### Error Response Example
```json
{
  "status": "Error",
  "message": "Error canceling job"
}
```

### Notes
Attempting to cancel completed or previously-canceled jobs will result in a 404 Not Found response.
```
Tokens:
Raw