curl --request POST \
--url https://helve.dev/v1/transcriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"audio_url": "https://example.com/recordings/standup.mp3",
"provider": "auto",
"diarize": true,
"keyterms": [
"Helve",
"Stirrup"
]
}
'import requests
url = "https://helve.dev/v1/transcriptions"
payload = {
"audio_url": "https://example.com/recordings/standup.mp3",
"provider": "auto",
"diarize": True,
"keyterms": ["Helve", "Stirrup"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
audio_url: 'https://example.com/recordings/standup.mp3',
provider: 'auto',
diarize: true,
keyterms: ['Helve', 'Stirrup']
})
};
fetch('https://helve.dev/v1/transcriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://helve.dev/v1/transcriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'audio_url' => 'https://example.com/recordings/standup.mp3',
'provider' => 'auto',
'diarize' => true,
'keyterms' => [
'Helve',
'Stirrup'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://helve.dev/v1/transcriptions"
payload := strings.NewReader("{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://helve.dev/v1/transcriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://helve.dev/v1/transcriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"tool": "transcription",
"status": "queued",
"provider": "assemblyai",
"model": "<string>",
"warnings": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}Transcribe a recording
Submits a prerecorded file by URL and returns a job immediately. Helve records the attempt before contacting the provider, retries rate limits, never re-sends an uncertain submission, and fails the job at its deadline rather than leaving it hanging. Poll GET /v1/jobs/{id} for the transcript.
curl --request POST \
--url https://helve.dev/v1/transcriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"audio_url": "https://example.com/recordings/standup.mp3",
"provider": "auto",
"diarize": true,
"keyterms": [
"Helve",
"Stirrup"
]
}
'import requests
url = "https://helve.dev/v1/transcriptions"
payload = {
"audio_url": "https://example.com/recordings/standup.mp3",
"provider": "auto",
"diarize": True,
"keyterms": ["Helve", "Stirrup"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
audio_url: 'https://example.com/recordings/standup.mp3',
provider: 'auto',
diarize: true,
keyterms: ['Helve', 'Stirrup']
})
};
fetch('https://helve.dev/v1/transcriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://helve.dev/v1/transcriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'audio_url' => 'https://example.com/recordings/standup.mp3',
'provider' => 'auto',
'diarize' => true,
'keyterms' => [
'Helve',
'Stirrup'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://helve.dev/v1/transcriptions"
payload := strings.NewReader("{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://helve.dev/v1/transcriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://helve.dev/v1/transcriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"audio_url\": \"https://example.com/recordings/standup.mp3\",\n \"provider\": \"auto\",\n \"diarize\": true,\n \"keyterms\": [\n \"Helve\",\n \"Stirrup\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"tool": "transcription",
"status": "queued",
"provider": "assemblyai",
"model": "<string>",
"warnings": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}{
"error": {
"type": "unauthorized",
"message": "<string>",
"detail": "<unknown>"
}
}Authorizations
An API key from the dashboard, sk_live_…, sent as Authorization: Bearer sk_live_….
Body
HTTPS URL of the recording, fetched by the provider. Signed URLs are fine; it must stay reachable until the provider has read it. No embedded credentials or fragments.
Which speech-to-text provider runs the job. auto (default) picks the first configured provider. The choice is persisted on the job before execution.
assemblyai, deepgram, elevenlabs, auto BCP-47-style language tag such as en or en-US. Omit to let the provider detect the language.
^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$Label speakers in words as speaker_0, speaker_1, … in order of first appearance. Default false.
Recognition hints: names, jargon, product terms. Supported on AssemblyAI, Deepgram Nova-3, and ElevenLabs Scribe v2; other models ignore them with a warning.
1word (default) returns per-word timings in result.words; none omits them.
word, none When true, any option the selected provider or model cannot honour rejects the request instead of producing a warning. Default false.
Provider-native options, validated by the adapter. Model selection lives here. Transport settings such as URLs, callbacks, and authentication cannot be overridden.
Show child attributes
Show child attributes
Response
Transcription accepted
The job id, job_…. Poll GET /v1/jobs/{id} with it.
^job_[0-9a-f-]{36}$transcription queued and running are in progress; completed carries result; failed carries error.
queued, running, completed, failed The provider selected for this job, resolved from auto.
assemblyai, deepgram, elevenlabs The provider model the job will run on.
Options the selected provider or model cannot honour. Empty when the request was accepted exactly.
Show child attributes
Show child attributes