Transcribe a file from your own bucket: what Sume STT audio_url needs

Short answer

Sume speech-to-text reads one thing: audio_url, a public HTTPS URL, and the tool description recommends one on the Sume media host. A recording that sits behind a private bucket or an expiring link is the case that causes trouble, so this post covers how to get such a file into a shape the job can read.

The MCP description for stt_create reads: audio_url is required, a public HTTPS URL, preferably on the Sume media host. Optional fields are language_code (a BCP-47 hint such as ko, omitted for auto-detect), duration_seconds (1 to 600, which improves the usage reservation), segmentation, metadata and the usual communication fields.

What the neighbours reject

The docs for the neighbouring endpoints are stricter, and they show the direction Sume takes. Video captions require a public HTTPS video_url that Sume can fetch, and the API rejects localhost, private-network, non-HTTPS, signed or private URLs and provider task URLs. Audio detach and video inspect accept only a media.sume.com artifact or asset of your workspace and never fetch from the open internet; off-host URLs fail with unsupported_media_source.

Based on that pattern, assume an expiring signed link is a bad input for STT as well, even though the STT description names only the public-HTTPS rule. Test one before you build on it.

Three routes get a private recording to a safe URL.

Detach is the clean path for video

The third route is the one the docs call the STT shape: 16 kHz mono. Audio detach takes only a Sume-hosted video, so import first, then detach. It costs $0.01 per job and uses worker ffmpeg only. The source can be up to 1800 seconds, but a whole track longer than 900 seconds needs a range, and the STT limit is 10 minutes per job, so plan chunks of 600 seconds or less.

Fields worth knowing

• Send duration_seconds when you know it. Without it Sume reserves one minute, and the public rate is $0.01 per audio minute.
• Do not send diarize or tag_audio_events. They are fixed server-side and the API rejects them.
• There is no timestamps flag: words[] always comes back with word, start and end.
• Keep your own record of the source URL beside the job id.

Checking the URL before you submit

A short check saves a failed job. Fetch the URL from a machine outside your network, with no cookies, and confirm it returns audio bytes and not a login page or a redirect to a sign-in. Do the same for a signed URL after it has aged: it must still be valid when the job starts, not only when you create it.

Prefer a media.sume.com URL when you can, as the docs recommend. Importing the file once with POST /v1/media-imports gives a stable address in your workspace and removes the expiry question.

Send duration_seconds when you know it, from 1 to 600; without it one minute is reserved.

• Test from outside your network, signed out.
• Signed URLs must outlive the job.
• Import to media.sume.com for a stable address.