Speech Intelligence API

Transcribe audio and video files using WAYSCloud Speech Intelligence.

How it works:

1. POST /v1/transcript/jobs — create a job, receive a presigned upload URL
2. Upload your file to the presigned URL (HTTP PUT, raw file body)
3. POST /v1/transcript/jobs/{job_id}/upload-complete — confirm upload and start processing
4. GET /v1/transcript/jobs/{job_id} — poll until status is ready
5. Read segments from the response, or use the export endpoint for SRT/VTT

Job statuses:

Status	Description
created	Job created, waiting for file upload
queued	Upload confirmed, waiting for processing
processing	Transcription in progress
ready	Complete — segments and default exports (TXT, JSON) available
failed	Processing failed (see error_message)
expired	Upload URL expired (file was never uploaded within 1 hour)

Default exports: txt and json are generated automatically when a job completes. srt and vtt can be generated on demand via POST /v1/transcript/jobs/{job_id}/export.

Supported inputs: Any file with an audio track — common containers include MP3, WAV, M4A, OGG, FLAC, WEBM, and MP4. Files are validated server-side using ffprobe; the file must contain at least one audio stream. Maximum file size: 2 GB.

Languages: Set language to auto (default) for automatic detection, or specify an ISO 639-1 code (e.g., no, en, sv, da, fr, de).

Pricing: Per-minute billing based on audio duration. See your dashboard for current rates.

Authentication: WAYSCloud API key via X-API-Key header or Authorization: Bearer <key>. Keys are created in the WAYSCloud dashboard under Account → API Keys.

Endpoints

Method	Path	Description
POST	/v1/transcript/jobs	Create transcription job
GET	/v1/transcript/jobs	List transcription jobs
GET	/v1/transcript/jobs/{job_id}	Get transcription job
DELETE	/v1/transcript/jobs/{job_id}	Delete transcription job
POST	/v1/transcript/jobs/{job_id}/upload-complete	Confirm upload complete
POST	/v1/transcript/jobs/{job_id}/export	Export transcription

POST /v1/transcript/jobs

Create transcription job

Create a transcription job and receive a presigned upload URL.

The returned upload_url is a presigned S3 PUT URL valid for 1 hour. Upload your file directly to this URL, then call the upload-complete endpoint to start processing.

If the file is not uploaded within 1 hour, the job expires automatically (status becomes expired).

Content validation: The server validates the file using ffprobe after upload — the file must contain at least one audio stream. The content_type field is metadata only; actual format detection is server-side.

Request Body:

Field	Type	Description
filename	string	Required. Original filename
content_type	string	Required. MIME type (e.g., audio/mpeg, audio/wav)
file_size_bytes	integer	Required. File size in bytes (max 2 GB)
language	string	ISO 639-1 language code or "auto" for detection

Example:

{
  "filename": "meeting-recording.mp3",
  "content_type": "audio/mpeg",
  "file_size_bytes": 15728640,
  "language": "auto"
}

Response:

Field	Type	Description
job_id	string
upload_url	string	Presigned S3 upload URL
upload_expires_in	integer	Upload URL expiry in seconds

Example:

curl -X POST https://api.wayscloud.services/v1/transcript/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/transcript/jobs

List transcription jobs

List transcription jobs for your account with optional status filter.

Response:

Field	Type	Description
jobs	array
total	integer
limit	integer
offset	integer

Example:

curl https://api.wayscloud.services/v1/transcript/jobs \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/transcript/jobs/

Get transcription job

Get full job details. When status is ready, the response includes transcription segments and available export artifacts with presigned download URLs.

Response:

Field	Type	Description
job_id	string
status	string	Values: created, queued, processing, ready, failed, expired
language	string	Detected or specified language code
original_filename	string
audio_duration_sec	number	Audio duration in seconds (available after processing)
processing_time_ms	integer	Total processing time in milliseconds
error_message	string	Error details (only when status is failed)
segments	array	Transcription segments (only included when status is ready, on detail endpoint)
artifacts	array	Available export artifacts with download URLs (only included when status is ready, on detail endpoint)
created_at	string
completed_at	string

Example:

curl https://api.wayscloud.services/v1/transcript/jobs/{job_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

DELETE /v1/transcript/jobs/

Delete transcription job

Delete a transcription job. The job is marked as deleted and S3 artifacts are cleaned up. The job will no longer appear in list results.

Response:

Field	Type	Description
status	string
job_id	string

Example:

curl -X DELETE https://api.wayscloud.services/v1/transcript/jobs/{job_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/transcript/jobs/{job_id}/upload-complete

Confirm upload complete

Confirm that the file has been uploaded to the presigned URL. This moves the job from created to queued and starts processing.

This endpoint is idempotent — if the job is already queued, processing, or ready, it returns the current status without re-queuing.

The server verifies that the file exists in S3 before accepting the confirmation. If the file is not found, returns 422.

Example:

curl -X POST https://api.wayscloud.services/v1/transcript/jobs/{job_id}/upload-complete \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/transcript/jobs/{job_id}/export

Export transcription

Generate an export artifact in the specified format. Returns a presigned download URL.

Formats:

• txt — Plain text transcript (auto-generated on completion)
• json — Structured JSON with segments and timestamps (auto-generated on completion)
• srt — SubRip subtitle format (generated on demand)
• vtt — WebVTT subtitle format (generated on demand)

txt and json are created automatically when a job reaches ready status. Calling this endpoint for those formats returns the existing artifact. srt and vtt are generated on first request and cached for subsequent calls.

The job must be in ready status. Returns 422 if the job has not completed processing.

Request Body:

Field	Type	Description
format	string	Required. Export format Values: txt, json, srt, vtt

Example:

{
  "format": "srt"
}

Response:

Field	Type	Description
artifact_id	string
format	string	Values: txt, json, srt, vtt
download_url	string
size_bytes	integer

Example:

curl -X POST https://api.wayscloud.services/v1/transcript/jobs/{job_id}/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---