Speech-to-text API with word timestamps: Sume STT 1.0

To get a transcript with word timestamps from the Sume API, send a public HTTPS audio_url to POST /v1/stt-1.0/transcribe. Sume STT 1.0 (sume/stt-1.0) runs it as a job, and the completed result carries the transcript text plus a words[] array with each word's start and end in seconds from the start of the audio.

STT 1.0 is specified in the OpenAPI document behind the Sume API reference, which the API reference docs page names as the source for exact request and response shapes. Job statuses and billing follow Core concepts. All were read on 2026-09-26.

How do I transcribe an audio file?

Send a JSON body with one required field, audio_url. The same body also works at POST /v1/models/sume/stt-1.0/runs. There is no flag for word timings: they are always returned.

• audio_url: a public HTTPS audio URL to transcribe.
• language_code: an optional BCP-47 language hint of 2–16 characters, such as en or ko. Omit it for auto-detect.
• duration_seconds: an optional integer from 1 to 600 used for the usage reservation. Omit it and Sume reserves for 1 minute.
• segmentation: optional. Send { "mode": "sentence" } to also get sentence segments.
• metadata, stored with the job request, plus the common communication fields mode, webhook_url, and wait_timeout_seconds.

curl -X POST https://api.sume.com/v1/stt-1.0/transcribe \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stt-interview-001" \
  -d '{
    "audio_url": "https://example.com/audio/interview.m4a",
    "language_code": "ko",
    "duration_seconds": 20,
    "mode": "async"
  }'

What does the transcript look like?

STT jobs return text and timings instead of media artifacts. Read them from GET /v1/jobs/:id/result once the job is completed.

How do I get sentence timestamps as well?

Add "segmentation": { "mode": "sentence" }. Sume groups the returned words into sentences on terminal punctuation and splits unpunctuated runs on silence. sentence is the only mode.

• Segments are gapless and ordered: each segment's end equals the next one's start.
• boundary_lead_ms (0–500, default 70) is the lead carried past a sentence's last word before the next segment starts. It is the same rule and default as TTS 1.0.
• Segments are time ranges over the submitted audio_url. No sliced files are produced, so cutting the audio is up to you.
• If no timed words come back, segmentation fails closed with a typed error.

Should I poll, wait, or use a webhook?

Every mode returns the job id in the first response, and GET /v1/jobs/:id/result answers 409 job_not_completed until result_ready is true.

• async (the default) returns at once with status_url, result_url, events_url, and cancel_url.
• sync and subscribe are the same bounded wait of up to wait_timeout_seconds (0–30). If the job is not finished by then, the response is still 2xx with the current job state and polling URLs. Keep polling status_url; do not submit a second paid job.
• webhook returns at once and sends a signed callback only for job.completed, job.failed, or job.canceled. Sending webhook_url without a mode selects webhook.
• If your client times out, keep the job id and recover through the jobs API. Reusing an Idempotency-Key with the same payload returns the original job; see idempotency keys for AI video APIs.

How much does speech-to-text cost?

API pricing lists speech transcription at $0.01 per audio minute, plus a 5.5% agent fee by default. The submit response quotes the estimate as usage.billable_amount_usd.

Sume reserves estimated usage when you submit, captures the cost on success, and refunds a job that fails or is canceled before capture. duration_seconds sizes that reservation. If the balance cannot cover the estimate, the submit returns 402 and no job starts.

Speech inside a Sume-hosted video can also be transcribed by video inspect, which runs STT 1.0 on the clip's audio.

What are the limits of STT 1.0?

The request schema accepts no fields beyond the eight described above. The documented bounds:

• duration_seconds: 1–600, so the hint tops out at 10 minutes.
• language_code: 2–16 characters.
• words[]: at most 20,000 entries, flagged by words_truncated if the cap is reached.
• Segmentation: sentence only, as time ranges, with no sliced audio.
• webhook_url: public HTTPS, up to 2,048 characters. Localhost, private-network, and non-HTTPS callback URLs are rejected.