curl --request POST \
--url https://api.pyai.com/v1/transcription/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"audio_url": "<string>",
"model": "pyai-hear-telephony",
"output_script": "original",
"channel": false,
"diarize": false,
"numerals": true,
"smart_format": false,
"dictation": false,
"drop_fillers": false,
"vocabulary": [
"<string>"
],
"output_formats": [
"json"
],
"redact": true,
"webhook_url": "<string>",
"trace": false,
"rule_pack": {},
"call_id": "<string>",
"pack_id": "<string>",
"customer_name": "<string>",
"crm_fields": {}
}
'import requests
url = "https://api.pyai.com/v1/transcription/jobs"
payload = {
"audio_url": "<string>",
"model": "pyai-hear-telephony",
"output_script": "original",
"channel": False,
"diarize": False,
"numerals": True,
"smart_format": False,
"dictation": False,
"drop_fillers": False,
"vocabulary": ["<string>"],
"output_formats": ["json"],
"redact": True,
"webhook_url": "<string>",
"trace": False,
"rule_pack": {},
"call_id": "<string>",
"pack_id": "<string>",
"customer_name": "<string>",
"crm_fields": {}
}
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: '<string>',
model: 'pyai-hear-telephony',
output_script: 'original',
channel: false,
diarize: false,
numerals: true,
smart_format: false,
dictation: false,
drop_fillers: false,
vocabulary: ['<string>'],
output_formats: ['json'],
redact: true,
webhook_url: '<string>',
trace: false,
rule_pack: {},
call_id: '<string>',
pack_id: '<string>',
customer_name: '<string>',
crm_fields: {}
})
};
fetch('https://api.pyai.com/v1/transcription/jobs', 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://api.pyai.com/v1/transcription/jobs",
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' => '<string>',
'model' => 'pyai-hear-telephony',
'output_script' => 'original',
'channel' => false,
'diarize' => false,
'numerals' => true,
'smart_format' => false,
'dictation' => false,
'drop_fillers' => false,
'vocabulary' => [
'<string>'
],
'output_formats' => [
'json'
],
'redact' => true,
'webhook_url' => '<string>',
'trace' => false,
'rule_pack' => [
],
'call_id' => '<string>',
'pack_id' => '<string>',
'customer_name' => '<string>',
'crm_fields' => [
]
]),
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://api.pyai.com/v1/transcription/jobs"
payload := strings.NewReader("{\n \"audio_url\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\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://api.pyai.com/v1/transcription/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"audio_url\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/transcription/jobs")
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\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "job_aZ09...",
"status": "queued",
"created_at": 123,
"updated_at": 123,
"result": {
"text": "[speaker_1] Hello everyone.",
"audio_seconds": 120,
"speakers": 1,
"word_timing_status": "partial",
"words": [
{
"word": "Hello",
"start": 0.42,
"end": 0.81,
"confidence": 0.98,
"speaker": "speaker_1",
"channel": 0
},
{
"word": "everyone.",
"start": null,
"end": null,
"timing_status": "unavailable",
"speaker": "speaker_1",
"channel": 0
}
],
"segments": [
{
"id": 0,
"text": "Hello everyone.",
"start": 0.42,
"end": 1.8,
"speaker": "speaker_1",
"channel": 0
}
]
},
"result_url": "<string>",
"error": "<string>"
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Create an async transcription job
Submit audio for batch transcription. Provide exactly one source:
either audio_url (an https URL we fetch; input is normally processed transiently)
a multipart upload (multipart/form-data with an audio file part and the same fields as form fields), or gpt_live: {session_id} for a connected project (gated availability).
GPT-Live: an organization owner/admin first configures the project connection through the management API. Uses a finalized stored OpenAI recording, downloaded transiently with a 100 MiB limit. Requires an active secret key with hear:transcribe and transcribe:jobs. No source audio is retained by this connector; normal result retention applies. OpenAI storage must be enabled and the session created with store: true. This is a post-call import, not an account-wide discovery service.
GPT-Live imports deduplicate by PyAI project, connection and session ID even without Idempotency-Key. Repeated submissions return the existing job; different normalized processing options return 409. Credential rotation retains the connection identity. Disconnect/reconnect creates a new identity. Failed jobs remain terminal; there is no automatic new billed job on resubmission.
Returns 202 immediately with a queued job; poll GET /v1/transcription/jobs/{id} or supply a webhook_url for a signed completion callback.
Use Idempotency-Key to safely retry JSON or multipart submissions. Keys are scoped to the authenticated project. The same key and normalized processing options return the original durable job, including after a lost response; changed audio bytes, upload filename, or normalized options return 409. Keep the same key after uncertain outcomes. Retries preserve the originating job’s billing identity and never restart terminal work.
Completed JSON results include word- and segment-level offsets in decimal seconds from the decoded source-media timeline. Silence is not removed or compacted; resampling and internal chunking do not shift later offsets.
Set channel: true for stereo (dual-channel) recordings to get exact speaker separation per channel. Use diarize: true for model-derived speaker labels on mono audio; do not set both.
Set vocabulary only when this job has known names, brands, products, or distinctive terms. PyAI uses up to five sanitized terms. If stored vocabulary is enabled for batch, request terms come first and stored suggestions fill remaining slots.
Set output_script: latin to represent recognized speech in Roman letters while keeping its original language: Hindi becomes Roman Hindi, not an English translation. Original-script text remains in source_text/source_word; timestamps, channel labels, existing Latin text, numbers and punctuation are preserved. Roman spellings and pronunciation of ambiguous words or names can vary. Omit this option or use original for the recognized script. This is independent of transcription_language and the Recap summary language.
Input limits: multipart uploads are limited to 1 GiB; audio_url downloads are limited to 512 MiB. There is no separate media-duration ceiling. Inputs must contain a decodable audio stream; the stable output formats are JSON, SRT, and VTT.
Retention: URL-fetched input bytes are normally transient. Organizations explicitly enabled for transcription fallback may have bounded audio chunks stored privately for processing/recovery; completed fallback inputs are deleted, and unresolved inputs expire within 7 days. Uploaded input audio is retained for up to 7 days and result artifacts for up to 30 days. This endpoint has no store: false mode. DELETE /v1/transcription/jobs/{id} cancels queued/running work; it is not an erasure endpoint.
Requires the transcribe:jobs scope.
curl --request POST \
--url https://api.pyai.com/v1/transcription/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"audio_url": "<string>",
"model": "pyai-hear-telephony",
"output_script": "original",
"channel": false,
"diarize": false,
"numerals": true,
"smart_format": false,
"dictation": false,
"drop_fillers": false,
"vocabulary": [
"<string>"
],
"output_formats": [
"json"
],
"redact": true,
"webhook_url": "<string>",
"trace": false,
"rule_pack": {},
"call_id": "<string>",
"pack_id": "<string>",
"customer_name": "<string>",
"crm_fields": {}
}
'import requests
url = "https://api.pyai.com/v1/transcription/jobs"
payload = {
"audio_url": "<string>",
"model": "pyai-hear-telephony",
"output_script": "original",
"channel": False,
"diarize": False,
"numerals": True,
"smart_format": False,
"dictation": False,
"drop_fillers": False,
"vocabulary": ["<string>"],
"output_formats": ["json"],
"redact": True,
"webhook_url": "<string>",
"trace": False,
"rule_pack": {},
"call_id": "<string>",
"pack_id": "<string>",
"customer_name": "<string>",
"crm_fields": {}
}
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: '<string>',
model: 'pyai-hear-telephony',
output_script: 'original',
channel: false,
diarize: false,
numerals: true,
smart_format: false,
dictation: false,
drop_fillers: false,
vocabulary: ['<string>'],
output_formats: ['json'],
redact: true,
webhook_url: '<string>',
trace: false,
rule_pack: {},
call_id: '<string>',
pack_id: '<string>',
customer_name: '<string>',
crm_fields: {}
})
};
fetch('https://api.pyai.com/v1/transcription/jobs', 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://api.pyai.com/v1/transcription/jobs",
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' => '<string>',
'model' => 'pyai-hear-telephony',
'output_script' => 'original',
'channel' => false,
'diarize' => false,
'numerals' => true,
'smart_format' => false,
'dictation' => false,
'drop_fillers' => false,
'vocabulary' => [
'<string>'
],
'output_formats' => [
'json'
],
'redact' => true,
'webhook_url' => '<string>',
'trace' => false,
'rule_pack' => [
],
'call_id' => '<string>',
'pack_id' => '<string>',
'customer_name' => '<string>',
'crm_fields' => [
]
]),
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://api.pyai.com/v1/transcription/jobs"
payload := strings.NewReader("{\n \"audio_url\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\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://api.pyai.com/v1/transcription/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"audio_url\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/transcription/jobs")
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\": \"<string>\",\n \"model\": \"pyai-hear-telephony\",\n \"output_script\": \"original\",\n \"channel\": false,\n \"diarize\": false,\n \"numerals\": true,\n \"smart_format\": false,\n \"dictation\": false,\n \"drop_fillers\": false,\n \"vocabulary\": [\n \"<string>\"\n ],\n \"output_formats\": [\n \"json\"\n ],\n \"redact\": true,\n \"webhook_url\": \"<string>\",\n \"trace\": false,\n \"rule_pack\": {},\n \"call_id\": \"<string>\",\n \"pack_id\": \"<string>\",\n \"customer_name\": \"<string>\",\n \"crm_fields\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "job_aZ09...",
"status": "queued",
"created_at": 123,
"updated_at": 123,
"result": {
"text": "[speaker_1] Hello everyone.",
"audio_seconds": 120,
"speakers": 1,
"word_timing_status": "partial",
"words": [
{
"word": "Hello",
"start": 0.42,
"end": 0.81,
"confidence": 0.98,
"speaker": "speaker_1",
"channel": 0
},
{
"word": "everyone.",
"start": null,
"end": null,
"timing_status": "unavailable",
"speaker": "speaker_1",
"channel": 0
}
],
"segments": [
{
"id": 0,
"text": "Hello everyone.",
"start": 0.42,
"end": 1.8,
"speaker": "speaker_1",
"channel": 0
}
]
},
"result_url": "<string>",
"error": "<string>"
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"title": "<string>",
"status": 123,
"type": "<string>",
"detail": "<string>",
"request_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Authorizations
Headers
Opt-in safe retry for JSON and multipart uploads, scoped to the authenticated project. Reusing the key with the same normalized options and upload bytes/filename returns the original durable job; changed input returns 409. GPT-Live sources use connection/session deduplication instead and ignore this header.
255Body
- Option 1
- Option 2
Spoken-language hint applied to every channel, chunk and speech span. Omit for automatic detection. Independent of the Recap summary language.
en, es, fr, de, hi, it, pt, nl, zh, yue, ar, id, ko, th, vi, ja, tr, ms, sv, da, fi, pl, cs, fil, fa, el, hu, mk, ro Tri-state inverse-text normalization for English final transcripts (never interim partials). true renders spoken numbers as digits (phones, currency, dates, ordinals). false keeps those spans in spoken form. Omitted keeps the live engine default: number formatting is ON for finals. Independent of smart_format.
Opt-in English punctuation and sentence capitalization on final transcripts only. Interim partials are never formatted. May change only case and punctuation; any failure returns the unformatted final. Default false. Independent of numerals. Non-English requests are unchanged.
Optional per-job terms for known names, brands, products, and other distinctive phrases. PyAI trims entries, removes case-insensitive duplicates, and keeps the first spelling and order. Entries shorter than 4 characters, longer than 64 characters, sentence-shaped input, non-string entries, and conservative common words are ignored. At most the first 5 valid terms are used. Invalid entries do not reject the job. When stored vocabulary is enabled for batch, request terms come first and stored suggestions fill any remaining slots. The effective list applies only to this job and does not select transcription language.
54 - 64Opt-in STT text redaction for all organizations. Select pci, pii, phi, numbers, aggressive_numbers, or individual entity types. English contextual entity recognition; digit masking also handles other scripts. Applies after primary or recovery transcription, before text, words, segments, subtitles and callbacks are returned. Does not mute source audio. Unknown selectors return 400; unavailable protection fails closed. See /guides/stt-redaction.
Trace compliance add-on: deterministic PII scan + redaction over the final transcript (SSN, card numbers, CVV-in-context, email, US phone — the pii_v0 entity set). The result carries the redacted transcript plus a trace summary (verdict, PII count). Patterns run on the formatted transcript, so pair with the default numerals (digits) for full effect. Requires the org's Trace entitlement on this surface (else 402); bills one Trace call. For stereo or diarized jobs, also set redact. When combined, the shared redactor retains these five categories plus the selected redact categories; rule_pack does not narrow that combined policy.
Response
Job accepted
Present on completed jobs (inline). Large results are offloaded to result_url instead.
Show child attributes
Show child attributes
{
"text": "[speaker_1] Hello everyone.",
"audio_seconds": 120,
"speakers": 1,
"word_timing_status": "partial",
"words": [
{
"word": "Hello",
"start": 0.42,
"end": 0.81,
"confidence": 0.98,
"speaker": "speaker_1",
"channel": 0
},
{
"word": "everyone.",
"start": null,
"end": null,
"timing_status": "unavailable",
"speaker": "speaker_1",
"channel": 0
}
],
"segments": [
{
"id": 0,
"text": "Hello everyone.",
"start": 0.42,
"end": 1.8,
"speaker": "speaker_1",
"channel": 0
}
]
}