Create a New Transcription Job

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.

Endpoint

POST https://api.speechischeap.com/v1/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).
can_parse_words	boolean	false	When enabled, includes a timecode for every word in the transcription. This costs a bit more; see pricing for details.
hotwords	string	null	Specific words or phrases to help improve transcription accuracy.
is_multilingual	boolean	false	When enabled, language will be auto-detected in each segment.
language	string	null	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	null	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 will be sent via a POST request.

Example Request

Using cURL

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" }'

Including all possible parameters

{
  "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

Synchronous Job Responses

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

Status Code	Description
201 Created	Job successfully created
400 Bad Request	Missing or invalid parameters
401 Unauthorized	Invalid or missing authentication token
500 Internal Server Error	Server-side error occurred

Success Response

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

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

Error Response

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

Missing required "input_url" parameter

Asynchronous Webhook Responses

Success

{
  "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

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

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

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 is_multilingual is enabled, the language parameter is ignored
• You are only charged for successfully completed transcriptions