Skip to main content

Upload a File

Upload an audio or video file and receive its transcript in the response. The connection stays open until transcription finishes. Use this for short recordings. For long or large files, use the Jobs API's Upload a File or Create a Job from a URL.

Endpoint​

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

Authentication​

Send your API key as a Bearer token in the Authorization header. To check a key without uploading a file, see API Health.

Authorization: Bearer YOUR_API_KEY

Request​

Send the request body as multipart/form-data.

ParameterTypeDefaultDescription
input_filefile-The audio or video file to transcribe (required). Edge accepts the same file types as the Jobs API. See Supported File Types.
can_parse_wordsbooleanfalseWhen enabled, includes a timecode for every word in the transcription. See Output and Add-ons for the output and Pricing for the price.
is_privatebooleanfalseWhen enabled, the response shows redacted instead of the file name, and Edge saves the job without its transcript.
languagestring""A code from Supported Languages, such as en. Send it in lowercase. If not provided, Edge detects the language once for the whole file.
minimum_confidencenumber0.5Filter out segments that fall below this confidence threshold. Must be between 0 and 1.

Enable a boolean with the exact value true. Any other value leaves it off. Edge ignores fields that aren't in this table, such as webhook_url and output_format, without an error.

Example Requests​

Using cURL to Upload a File​

curl --request POST \
--url https://edge.speechischeap.com/v2/jobs/ \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'input_file=@/path/to/your/audio-file.mp3'

Including All Optional Parameters​

curl --request POST \
--url https://edge.speechischeap.com/v2/jobs/ \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'input_file=@/path/to/your/audio-file.mp3' \
--form 'can_parse_words=true' \
--form 'is_private=true' \
--form 'language=en' \
--form 'minimum_confidence=0.5'

Response​

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

Status CodeDescription
200 OKEdge processed the request. Check status to see whether the transcription completed or failed.
400 Bad RequestMissing input_file, a body that isn't multipart/form-data, or an invalid parameter
401 UnauthorizedMissing, invalid, expired, or revoked API key
402 Payment RequiredThe API key is known, but its billing isn't active.
500 Internal Server ErrorEdge couldn't determine the audio's duration, or hit an unexpected error

Edge returns a failed transcription with HTTP 200, so check status before you read output. Every other error is plain text, not JSON.

Completed Response​

This example was created with can_parse_words enabled and no language:

{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {
"duration": 2.944,
"request": {
"can_parse_words": true,
"input_file": "audio-file.mp3",
"is_private": false,
"language": null,
"minimum_confidence": 0.5
},
"segments": [
{
"confidence": 0.987,
"end": 2.24,
"id": 1,
"language": "en (99.95%)",
"processing_duration_in_s": 0.321,
"start": 0.32,
"text": "Hello, and welcome.",
"words": [
{ "end": 0.8, "start": 0.32, "text": "Hello," },
{ "end": 1.12, "start": 0.8, "text": "and" },
{ "end": 2.24, "start": 1.12, "text": "welcome." }
]
}
]
},
"status": "COMPLETED"
}

The fields mean the same as in a Jobs API job, which Output and Add-ons describes. In Edge responses:

  • language is the same in every segment, because Edge detects the language once for the whole file. The Jobs API detects it for each segment.
  • id counts up from 1 with no gaps, because Edge removes segments below minimum_confidence before it numbers the rest.
  • processing_duration_in_s is the same in every segment. It's the total transcription time divided by the number of segments before low-confidence segments are removed, so the values in the response can add up to less than the total.
  • words is an empty array unless can_parse_words is true. When it is, each entry has text, start, and end.
  • output.request.input_file is the uploaded file's name, or redacted when is_private is true. output.request.language is null when you don't send a language.

Failed Response​

When Edge can't transcribe the file, for example because it can't decode it, the response is:

{
"id": "00000000-1111-7222-b333-444444444444-sic",
"output": {
"error": "Failed to decode audio file"
},
"status": "FAILED"
}

output.error is the message from the transcription engine, so its wording can vary. You aren't charged for a failed transcription.

Errors​

See Edge API errors for every message and how to recover. The most likely are a 401 for a missing or invalid API key, a 400 for a missing input_file or a minimum_confidence that isn't between 0 and 1, and a FAILED status for a file Edge can't decode.

Notes​

  • Edge doesn't check a file's type, size, or duration before it transcribes. A file it can't decode comes back as FAILED.
  • Edge doesn't check language against Supported Languages, so use a listed code.
  • Edge allows requests from any origin, so browser code can call it directly. Anyone who loads the page can read an API key placed in its code.
  • Keep the trailing slash in POST /v2/jobs/. Without it, Edge returns 404 Not Found.
  • Edge has its own per-minute rates. See Pricing. Each request rounds the file's duration up to whole minutes, so a 7-second file counts as one minute. can_parse_words adds a charge for the same minutes. You're charged only when status is COMPLETED.