Batch Transcription API

Upload audio and video files for asynchronous speech-to-text transcription.

What is Batch Transcription?

Batch transcription processes pre-recorded audio/video files asynchronously:

1. Create a transcription session
2. Upload the audio or video file (or point the session at a URL)
3. Wait for processing (minutes to hours depending on file size)
4. Retrieve the transcript with timestamps, speakers, and formatting

Best for: Podcasts, interviews, meetings, video subtitles, recorded content

All requests use the base URL https://api.scriptix.io and require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Quick Start

1. Create a Session

Send the transcription options as JSON. The session is created in the New state, ready to receive a file.

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en-us",
    "diarization": true,
    "punctuation": true
  }'

Response:

{
  "result": {
    "session_id": "01HQ2ABCXYZ...",
    "status": "New",
    "language": "en-us"
  }
}

Use the returned session_id for the following steps.

2. Upload the File

Upload the file directly by sending it as the request body:

curl -X PUT "https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @meeting.mp3

The upload triggers processing automatically. For large files or unstable connections, use the pre-signed upload or TUS Upload instead.

3. Check Status

curl "https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Check Status for the full response and status values.

4. Get the Transcript

Once the session reports Finished, retrieve the document:

curl "https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}/document/{document_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Retrieve Results for formats and options.

Session Options

Pass any of these fields in the JSON body when creating a session:

Field	Type	Description
language	string	Required. Language code, e.g. en-us, nl, fr
diarization	boolean	Detect and label different speakers (default false)
min_speakers	integer	Minimum speakers for diarization (1-20)
max_speakers	integer	Maximum speakers for diarization (1-20)
punctuation	boolean	Add punctuation to the transcript (default false)
multichannel	boolean	Transcribe each audio channel separately (default false)
media_source	string (URL)	Fetch the media from a URL instead of uploading a file
webhook_url	string (URL)	Receive a notification when processing completes
webhook_method	string	POST (default) or PUT
webhook_headers	array	Extra headers to send with the webhook
folder_id	integer	Place the session in a specific folder
export_template_id	integer	Export template to auto-apply after transcription
meta_data	object	Arbitrary key-value metadata (e.g. meeting_id)
keep_source	boolean	Keep the uploaded media after processing (default true)

Upload Methods

You can provide the media in three ways:

Direct upload

Create the session, then PUT the file to /api/v3/speech-to-text/session/{session_id} as shown in the Quick Start. Best for small and medium files.

Pre-signed upload

For large files, request a time-limited upload URL and upload directly, bypassing the API server:

# 1. Request an upload URL
curl -X POST "https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "result": {
    "upload_url": "https://download.scriptix.io/...",
    "expires_at": "2026-01-17T12:00:00Z",
    "session_id": "01HQ2ABCXYZ...",
    "max_file_size": 5368709120
  }
}

# 2. Upload the file to the returned URL
curl -X PUT "UPLOAD_URL" --data-binary @meeting.mp3

# 3. Confirm the upload to start processing
curl -X POST "https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}/upload-complete" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fetch from a URL

Set media_source to a publicly reachable or pre-signed URL when creating the session, and the server downloads the media itself. No upload step is needed.

For resumable uploads of very large files, see TUS Upload.

Supported File Formats

Audio Formats

• MP3 (.mp3)
• WAV (.wav)
• FLAC (.flac)
• M4A (.m4a)
• AAC (.aac)
• OGG (.ogg)

Video Formats

• MP4 (.mp4)
• MOV (.mov)
• AVI (.avi)
• MKV (.mkv)
• WEBM (.webm)

Note: Audio is extracted automatically from video files.

Processing Time

Typical processing time is a fraction of the audio duration and depends on file size, audio quality, enabled features (such as diarization), and current load.

Webhooks

Instead of polling, set webhook_url when creating the session to be notified when transcription completes:

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en-us",
    "webhook_url": "https://yourapp.com/webhook"
  }'

See the Webhooks Guide for payload details.

API Endpoints

Method	Endpoint	Description
POST	/api/v3/speech-to-text/session	Create a transcription session
PUT	/api/v3/speech-to-text/session/{session_id}	Upload the file directly
POST	/api/v3/speech-to-text/session/{session_id}/upload-url	Get a pre-signed upload URL
POST	/api/v3/speech-to-text/session/{session_id}/upload-complete	Confirm a pre-signed upload
POST	/api/v3/files/	Start a resumable TUS upload
GET	/api/v3/speech-to-text/session/{session_id}	Check session status
GET	/api/v3/speech-to-text/session/{session_id}/document/{document_id}	Retrieve the transcript

Complete Example

API_KEY="YOUR_API_KEY"
BASE="https://api.scriptix.io/api/v3/speech-to-text"

# 1. Create the session and capture the session_id
SESSION_ID=$(curl -s -X POST "$BASE/session" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "en-us", "diarization": true}' \
  | jq -r '.result.session_id')

# 2. Upload the file (processing starts automatically)
curl -X PUT "$BASE/session/$SESSION_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @meeting.mp3

# 3. Poll status until the session is finished
curl -s "$BASE/session/$SESSION_ID" \
  -H "Authorization: Bearer $API_KEY"

Next Steps

• TUS Upload - Large file upload
• Check Status - Status polling
• Retrieve Results - Get transcripts
• Webhooks - Webhook setup