This guide walks you through the basics of creating and managing STT operations with the Shqip.ai API.
You’ll learn how to:

• Create a transcription job

• List your jobs (with pagination)

• Fetch details of a job

• Update name/description

• Delete a job

---

 Base URLs

• Production: https://platform.shqip.ai

• Dev: https://platform-dev.shqip.ai

While testing, stick to the dev URL.
For production, switch all endpoints to https://platform.shqip.ai.

Authentication

All requests require an API key: X-API-Key: <YOUR_API_KEY>

1. Create an Operation

Endpoint:

POST /stt-operation 

Body: multipart/form-data (file + text fields)

Example (cURL): curl -X POST "https://platform.shqip.ai/stt-operation" \ -H "X-API-Key: $API_KEY" \ -F "file=@/path/to/audio.mp3" \ -F "name=Interview demo" \ -F "description=Testing API quickstart" \ -F "split_speakers=false" \ -F "export_cc_files=false" \ -F "export_word_file=false" \ -F "encode_subtitles=false" \ -F "uppercase_encoded=false" \ -F "word_highlight_encoded=false" \ -F "max_chars_per_line=42" \ -F "max_lines_per_subtitle=2" \ -F "custom_webhook_url="

Response:

{ "message": "Operation created", "operation_id": "op_1234abcd" }

2. List Operations

Endpoint:

GET /stt-operations?sort=true&page=1&size=10 

Example (cURL): curl -X GET "https://platform.shqip.ai/stt-operations?sort=true&page=1&size=10" \ -H "X-API-Key: $API_KEY"

Parameters:

• page → page number (min 1)

• size → results per page (1–100)

• sort → true/false

3. Get Operation Details

Endpoint:

GET /stt-operation/{operation_id} 

Example (cURL): curl -X GET "https://platform.shqip.ai/stt-operation/op_1234abcd" \ -H "X-API-Key: $API_KEY"

Response includes: status, transcription fields, timestamps, file metadata.

4. Update an Operation

Endpoint (dev):

PUT /stt-operation/{operation_id} Base URL: https://platform-dev.shqip.ai 

Example (cURL): curl -X PUT "https://platform-dev.shqip.ai/stt-operation/op_1234abcd" \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Updated name","description":"Updated description"}'

5. Delete an Operation

Endpoint:DELETE /stt-operation/{operation_id}

Example (cURL): curl -X DELETE "https://platform.shqip.ai/stt-operation/op_1234abcd" \ -H "X-API-Key: $API_KEY"
 

Webhooks

When creating a job, include a custom_webhook_url.
The API will POST back to your server once transcription completes.

Example:

-F "custom_webhook_url=https://yourapp.ngrok.io/webhooks/shqipai/"

---

 Key Points

• Use dev base URL for testing, production for real jobs.

• Always include the X-API-Key header.

• multipart/form-data booleans must be "true" / "false" strings.

• Handle pagination when listing jobs.

• Use webhooks for async workflows.