Whisper-transkribering

Tools erbjuder en köbaserad Whisper-tjänst för media-URL:er och uppladdade ljud-/videofiler.

Den här sidan fokuserar på det publika kontraktet: vad funktionen gör, hur användare och klienter använder den, vilka endpoints som finns och vad klienter ska förvänta sig i request/response.

Vad funktionen gör

Whisper i Tools kan:

köa media för transkribering
visa live-status för kö och jobb
spara färdigt transcript
valfritt generera transcriptanalys
valfritt generera transcriptöversättningar
valfritt lägga till uppskattade talaretiketter när sådana finns
skapa en publik transcript-share-sida

Åtkomstmodeller

Inloggat webb-/JWT-API

Det vanliga Whisper-gränssnittet och det autentiserade API:t använder:

inloggad webbsession, eller
JWT bearer från POST /api/account/login

Behörigheter på användarnivå:

whisper.use för vanlig köåtkomst
whisper.manage för admin/full köåtkomst och run-now-funktioner
provider_openai när transcriptanalys/översättningar ska köras för en icke-admin-användare

Tokenbaserat transcribe-API

Tools exponerar nu också ett separat server-till-server-API för tokenbaserade integrationer.

Authkrav:

en aktiv personlig token med provider provider_whisper_api
rekommenderad transport: Authorization: Bearer YOUR_API_TOKEN
tokenägaren måste ha whisper.api
tokenägaren måste också ha vanlig Whisper-åtkomst (whisper.use)
adminanvändare passerar vanliga behörighetskontroller

Äldre transport via X-Api-Key eller apikey kan fortfarande finnas kvar för bakåtkompatibilitet, men nya integrationer bör använda Authorization-headern.

Köbeteende

Whisper-jobb körs asynkront.

Jobbstatusar:

queued
downloading
transcribing
finalizing
completed
failed

Jobb kan nu också exponera vilket köspår de kommer från:

queue_channel="web"
queue_channel="api"

Det betyder att inloggade kö-/detaljvyer och autentiserade /api/whisper/jobs*-payloads kan visa om ett jobb kommer från den vanliga användarkön eller från det tokenbaserade API-spåret.

Adminägda jobb prioriteras före vanliga jobb när arbete claimas från kön.

Webbgränssnitt

`/whisper`

Den inloggade kön låter användaren:

skicka in en media-URL
ladda upp en mediafil
välja modell och språkhints
sätta valfri titel/etikett och fritextnotering
välja analys-/översättningsspråk
följa liveprogress
öppna detaljsidor för jobb

`/whisper/jobs/{jobId}`

Den inloggade detaljvyn visar:

aktuell status och progress
källtitel/beskrivning
runtime-logg
transcript
transcriptanalys
transcriptöversättningar
speaker-aware transcript när det finns
status för publik share-länk

Färdiga jobb kan skapa en publik transcript-share-sida.

Publik transcript-share-sida

Färdiga transcript kan exponeras via en tokeniserad publik sida under:

/shared/whisper/transcript/{token}

Share-sidan är till för läsning/delning av transcriptet, inte för köadministration.

För tokenbaserade API-jobb kan Tools nu skapa den share-sidan automatiskt när transcriptet blir klart, och callback-payloaden innehåller då den direkta share-länken.

Autentiserat Whisper-API (`/api/whisper/*`)

Dessa endpoints använder inloggad webb-/JWT-auth, inte den dedikerade Whisper-API-token.

`GET /api/whisper/status`

Returnerar kösummering och capability-flaggor.

Typisk responseform:

{
  "ok": true,
  "summary": {
    "queued": 3,
    "processing": 1,
    "completed": 21,
    "failed": 2
  },
  "can_manage_all": false,
  "config": {
    "enabled": true,
    "default_model": "large",
    "upload_max_mb": 64,
    "upload_limit": {
      "configured_mb": 200,
      "php_upload_max_mb": 64,
      "php_post_max_mb": 128,
      "effective_max_mb": 64,
      "effective_max_label": "64 MB",
      "limited_by_php": true
    },
    "ytdlp_configured": true
  }
}

upload_max_mb visar nu den praktiska/effektiva gränsen för uppladdade Whisper-filer på den aktuella hosten, och additiv config.upload_limit kan förklara när PHP:s upload-/body-gränser ligger lägre än Whisper-konfigurationens egen cap.

`GET /api/whisper/jobs?limit=100`

Returnerar synliga Whisper-jobb för den autentiserade användaren.

`POST /api/whisper/jobs`

Köar ett nytt Whisper-jobb.

Stödda requeststilar:

JSON/form body med source_url
multipart/form-data med media_file

Viktig regel:

skicka antingen source_url eller media_file, inte båda
om den uppladdade filen är för stor för den aktuella hosten, bara laddas upp delvis eller stoppas av PHP/temp-lagringsfel, returnerar endpointen nu ett tydligare 422-valideringsfel under media_file i stället för bara det generiska “failed to upload”-meddelandet

Exempel på JSON-body:

{
  "source_url": "https://example.com/audio.mp3",
  "source_label": "Intervju med kund",
  "source_note": "Inspelat uppföljningssamtal med support.",
  "model": "large",
  "language": "sv",
  "analysis_language": "sv",
  "translation_target_languages": ["en"]
}

`GET /api/whisper/jobs/{jobId}`

Returnerar ett synligt Whisper-jobb.

Additiva jobbfält inkluderar nu bland annat:

queue_channel
queue_channel_label
source_type
source_label
source_note
source_mime
source_size_bytes
source_duration_seconds
source_duration_human
stage_label
stage_detail
runtime_log[]
liveness
analysis
translations[]
diarization
share
callback (främst relevant för API-köjobb)

`POST /api/whisper/jobs/{jobId}/analyze`

Kör transcriptanalys för ett färdigt transcript.

Guardrails:

transcript måste redan finnas
icke-admin-användare måste ha OpenAI-access

`POST /api/whisper/jobs/{jobId}/cancel`

Begär kooperativ cancel av ett aktivt jobb.

`POST /api/whisper/jobs/{jobId}/restart`

Köar om ett failat/köat jobb för ny körning.

`DELETE /api/whisper/jobs/{jobId}`

Tar bort ett jobb som inte längre processas aktivt.

`POST /api/whisper/run-now`

Admin-/managerhjälpare.

Requestbody kan exempelvis innehålla:

{
  "limit": 1,
  "reset_failed": true
}

Tokenbaserat transcribe-API (`/api/whisper/transcribe/*`)

Det här är det dedikerade server-till-server-API:t med callbackflöde.

`GET /api/whisper/transcribe/status`

Returnerar kösummering för det tokenbaserade API-köspåret.

`GET /api/whisper/transcribe/jobs?limit=100`

Returnerar synliga jobb från API-köspåret.

`GET /api/whisper/transcribe/jobs/{jobId}`

Returnerar ett synligt API-köjobb.

`POST /api/whisper/transcribe`

Köar ett nytt tokenautentiserat Whisper-jobb.

Obligatoriskt fält:

callback_url

Stödda submit-stilar:

URL-jobb via source_url
multipart-filjobb via media_file

Guidning för upload-validering:

när den uppladdade filen är större än hostens aktuella praktiska gräns kan API:t nu returnera 422 med errors.media_file[] som förklarar den effektiva Whisper-uploadgränsen
samma media_file-validering används nu också för partiella uppladdningar, saknad temp-mapp, skrivfel och andra PHP-relaterade uploadtransportfel innan jobbet hunnit köas

Token-API:t accepterar samma additiva metadata som den vanliga kö-endpointen, inklusive:

source_label
source_note
model
language
analysis_language
translation_target_languages[]
disable_diarization

Exempel på JSON-body:

{
  "source_url": "https://example.com/audio.mp3",
  "callback_url": "https://api.example.test/whisper/callback",
  "source_label": "Kundintervju",
  "source_note": "Transkribera och skicka slutresultatet tillbaka till vår integration.",
  "model": "large",
  "language": "en",
  "analysis_language": "en",
  "translation_target_languages": ["sv"]
}

Exempel på lyckad respons:

{
  "ok": true,
  "message": "Whisper API job queued. A callback will be sent when the job reaches a terminal state.",
  "job": {
    "id": 123,
    "queue_channel": "api",
    "queue_channel_label": "API queue",
    "status": "queued",
    "callback": {
      "url": "https://api.example.test/whisper/callback",
      "status": "pending",
      "http_status": null,
      "last_attempt_at": null,
      "delivered_at": null,
      "error": null
    },
    "share": null
  }
}

Callbackkontrakt

När ett tokenautentiserat Whisper-API-jobb når terminalstatus completed eller failed skickar Tools en JSON-POST till den angivna callback_url.

Callback-envelope:

{
  "ok": true,
  "event": "whisper.job.completed",
  "job": {
    "job_id": 123,
    "status": "completed",
    "status_label": "Completed",
    "queue_channel": "api",
    "queue_channel_label": "API queue",
    "source": "Kundintervju",
    "model": "large",
    "language": "en",
    "job_url": "https://tools.example.test/whisper/jobs/123",
    "share_url": "https://tools.example.test/shared/whisper/transcript/example-token-redacted",
    "transcript_text": "...",
    "analysis_text": "...",
    "translations": [],
    "share": {
      "url": "https://tools.example.test/shared/whisper/transcript/example-token-redacted"
    }
  }
}

Failade callbacks använder event="whisper.job.failed" och kan innehålla failure_error i stället för transcript/share-data.

Klientrekommendationer:

behandla callbacken som en asynkron terminal-notifiering
lagra den idempotent med job.job_id som nyckel
anta inte att share-URL finns på failade jobb
anta inte att transcriptanalys/översättningar alltid finns för varje konto

Felhantering

Vanliga felklasser:

401 oautentiserad / token avvisad
403 saknad behörighet
404 jobb saknas eller är inte synligt för anroparen
422 validerings- eller business-regelfel
429 throttling
5xx tillfälligt backend-/providerfel

Rate limiting

Whisper-rutterna använder en generell policy throttle:120,1.

Klienter bör ändå implementera vanlig backoff för upprepad polling eller temporära fel.

Säkra klientrekommendationer

Föredra Authorization: Bearer YOUR_API_TOKEN
Behandla callback_url som obligatoriskt för tokenbaserade submits
Räkna med att jobb avslutas asynkront
Visa gärna queue_channel och queue_channel_label i operatörs-/debuggränssnitt
Behandla transcript_text som primärresultat och speaker_aware_transcript som additiv hjälputdata
Behandla share.url som publik åtkomst och hantera den försiktigt

Tornevall Networks