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/status/{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 response codes to indicate the success or failure of requests. Error responses will include a JSON object with more details about the error.