Create a New Transcription Job

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

Endpoint

POST https://api.speechischeap.com/v2/jobs/

Authentication

Requires authentication using a Bearer token in the HTTP header:

Authorization: Bearer YOUR_API_KEY

Request Body

The request body should be a JSON object with the following parameters:

Parameters

Parameter	Type	Default	Description
input_url	string	-	The URL of the audio file to transcribe (required). Must be between six seconds and 24 hours long.
can_label_audio	boolean	false	When enabled, includes an audio classification label in the transcription. See add-ons for pricing.
can_parse_words	boolean	false	When enabled, includes a timecode for every word in the transcription. See add-ons for pricing.
hotwords	string	""	Specific words or phrases to help improve transcription accuracy.
language	string	""	Two-letter ISO 639-1 language code (e.g., "en"). If not provided, the language will be auto-detected from the first segment.
prompt	string	""	Custom prompt to adjust transcription style. Should match the audio language.
segment_duration	number	30	Duration of each transcription segment in seconds.
webhook_url	string	""	The URL where the transcription results may be sent to via a POST request.

Example Request

Using 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

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

Response

Synchronous Job Responses

The API uses standard HTTP status codes to indicate the outcome of your request:

Status Code	Description
202 Accepted	The job was successfully created and is being processed
400 Bad Request	Missing or invalid parameters
401 Unauthorized	Invalid or missing authentication token
500 Internal Server Error	Server-side error occurred

New Job Response

When a new transcription job is created successfully, you'll receive a 202 Accepted status code with the following response:

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

Error Responses

Error responses include a message explaining what went wrong. For example:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Missing required "input_url" parameter

Asynchronous Webhook Responses

Success

When the job completes successfully, the webhook will receive a completion response similar to the following:

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

Failure

If the job fails to complete, the webhook will receive the following error response:

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

Cancelation

If the job is canceled, the webhook will receive the following confirmation response:

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

Notes

• The audio file at input_url must be publicly accessible
• For best results, omit all optional parameters and let the system auto-configure based on the input
• When language is not provided, the system will auto-detect the audio language of each segment
• You are only charged for successfully completed transcriptions