Shöpot API Reference

Доступно на Русском

Introduction

The Shopot.ai transcription API allows you to convert audio-video files to text. You can interact with the API through HTTP requests from any language.

Authentication

We use API keys for authentication. Your key can be obtained from the support team at hi@shopot.ai. Please store your key securely and never expose it in apps and browsers, only store it on backend of your server in an environment variable or other key management service. All API requests require an API key to be included in an Authorization header:

Authorization: Bearer $SHOPOT_API_KEY

Available Methods

The Shopot API supports two primary methods for submitting audio files for transcription:

Create Transcription

POST https://api.shopot.ai/v1/transcribe

Transcribes an audio file and processes the transcript through an LLM. Returns a unique request id and status.

Request body

url or file string Required
Depending on the selected source of the file, you will use either the URL or File parameters. The URL should link to the publicly available file on your/remote server. The file size is limited to 200 MB. Contact support here if you need larger uploads.
language string Optional Defaults to Auto detection
The language of the audio. Provide the input language in ISO-639-1 format. If nothing is provided, auto-detection will occur by the first seconds of the audio. Supported language codes: af, ar, az, be, bg, bs, ca, cs, cy, da, de, el, en, es, et, fa, fi, fr, gl, he, hi, hr, hu, hy, id, is, it, ja, kk, ko, lt, lv, mi, mk, ms, ne, nl, no, pl, pt, ro, ru, sk, sl, sr, sv, sw, th, tr, uk, vi, zh
initial_prompt string Optional
Optional prompt to define special vocabulary or guide the model to correctly transcribe namings and terminology. Should match the input language.
vad_filter boolean or null Optional Defaults to True
Voice activity detection filter used to cut out the silences and speed up the transcription process. When having a low-level input file or low-quality file it is recommended to run the request with the false option.
Options: true or false.
disable_diarization boolean Optional Defaults to False
By default, the model will diarize the file and return the transcript with text allocated to detected speakers.
Options: true or false.

callback_url string Optional
Webhook URL to be called by POST method to return the results after processing is completed or failed. The service will attempt delivery 3 times with a 60-second delay between attempts. When delivering processing results, the task status changes to WEBHOOK_DELIVERED or WEBHOOK_FAILED. When delivering processing errors, the status does not change.
callback_id string Optional
Any ID value you need to identify your initial request that will be sent to Webhook when returning the result. This parameter is passed in the request headers as x-callback-id, as well as in the response body.
template string Optional Processing template used to define a customized workflow created by the Shopot team for your organization, such as post-processing options through language models or workflow automation. You receive this parameter from your manager in the Shopot team.

Returns

The response of the API with id and status of the job.
Possible statuses:
ACCEPTED - request accepted by the API service
IN_QUEUE - request in the queue for transcription
IN_PROGRESS - request being transcribed
COMPLETED - processing completed if no callback_url is set
WEBHOOK_DELIVERED - processing completed, webhook successfully delivered to the set callback_url
WEBHOOK_FAILED - webhook delivery failed to the set callback_url
FAILED - processing error with error text
Example request
Response

Getting the results or status of transcription

To get the status of a transcription task, you always need to pass through authentication by supplying the Authorization header with Bearer $SHOPOT_API_KEY, using the following endpoint:

GET https://api.shopot.ai/v1/transcribe/{id}

Returns

The response of the API with id and status of the job.
Possible statuses:
ACCEPTED - request accepted by the API service
IN_QUEUE - request in the queue for transcription
IN_PROGRESS - request being transcribed
COMPLETED - processing completed if no callback_url is set
WEBHOOK_DELIVERED - processing completed, webhook successfully delivered to the set callback_url
WEBHOOK_FAILED - webhook delivery failed to the set callback_url
FAILED - processing error with error text
Example request
Processing response

The transcription JSON

id string Task id
status string
Status of the processing.
balance_minutes string
Remaining balance of minutes or credits on your account.
output string
Results of transcription, including:
duration string
Duration of the file in seconds.
language string
Language of the file, either the one sent with the request or the one detected automatically.
list array
Transcription timing, speakers, text
start string
Timecode start of text segment in seconds from the beginning of the file.
end string
Timecode end of text segment in seconds from the beginning of the file.
speaker string
Speaker ID detected by the model.
text string
Text of the segment.
JSON response

Errors

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses will include a JSON object with more details about the error.

HTTP Code Detail Description
400 Invalid URL or file not accessible The provided URL is either malformed or the server couldn't access the file. Users should check if the URL is correct and the resource is available.
400 Failed to resolve URL: [details] The URL provided could not be resolved. This may happen due to network issues or the URL pointing to a non-existent resource. Check the URL for typos or try again later.
400 The 'URL' field must be a string The url field provided in the request body must be a valid string. Make sure it's not a list or any other data type.
400 Invalid 'URL' format. Must start with http or https The URL provided for the file must start with either http:// or https://.
400 File or URL required At least one of file or url must be provided. Ensure that you include either a file upload or a URL to transcribe.
400 The 'callback_url' field must be a string The callback_url provided must be a valid string. Make sure it's correctly formatted and is a valid URL.
400 Invalid 'callback_url' format. Must start with http or https The callback URL must be valid and should start with either http:// or https://.
400 Invalid language format. Must be a string The language parameter must be a string. Make sure it's one of the accepted language codes.
400 Invalid language code: [language_code] The provided language is not supported. Refer to the documentation for a list of accepted language codes.
403 Forbidden: Invalid API key The API key provided is incorrect or not authorized. Make sure you're using the correct key.
403 Forbidden: Invalid API key format The API key must start with the prefix Bearer. Make sure it's formatted correctly.
403 Insufficient balance The user does not have enough balance to proceed with the transcription. Please top-up your balance to continue.
404 Request not found The provided request_id does not match any existing request. Double-check that the request_id is correct.
413 File size exceeds [max_size]MB limit The provided file exceeds the maximum allowed file size. Please upload a smaller file or contact support to discuss higher file limits.
415 Unsupported file extension: [file_extension] The provided file extension is not supported. Accepted extensions include .mp3, .wav, .flac, .ogg, .aac, .m4a, .wma, .mp4, .mov, .avi, .mkv, .webm, .wmv, .m4v, .flv.
500 Transcription result not found The transcription process failed to generate a result. This may be due to server issues. Please try again later or contact support.
500 Failed to access the file or invalid URL The system could not access the provided URL, which may indicate an issue with the file availability.