Grimoire

Transcriere audio cu Venice

4 min read

Transcriere audio cu Venice

Ce face

venice-audio-transcription trimite un fișier audio la Venice și întoarce transcriptul. Folosește endpoint-ul POST /api/v1/audio/transcriptions, cu multipart/form-data, compatibil cu stilul OpenAI pentru audio.transcriptions.create().

Pe scurt: îi dai un fișier audio real, alegi un model STT — speech-to-text — și primești textul. Poate returna JSON sau text simplu. Pentru timestamps, nu folosi response_format=text; ai nevoie de o formă JSON / subtitrare care păstrează timpii.

Modele documentate:

  • nvidia/parakeet-tdt-0.6b-v3 — default, rapid, English-first.
  • openai/whisper-large-v3 — multilingual, respectă hint-ul language.
  • fal-ai/wizper — variantă Whisper, compromis bun calitate/latency.
  • elevenlabs/scribe-v2 — bun pe audio zgomotos.
  • stt-xai-v1 — xAI Speech-to-Text.

Catalogul curent se verifică prin GET /models?type=asr. Prețul ASR este pe secundă audio, deci costul crește cu durata fișierului. Fișiere acceptate: wav, wave, flac, m4a, aac, mp4, mp3, ogg, webm.

Când îmi folosește

Îl folosești când vrei să transformi vorbire în text: voice notes, ședințe, interviuri, podcasturi, fragmente audio scurte sau fișiere pe care vrei să le cauți ulterior ca text.

Îți folosește și când vrei timestamps pentru subtitrări, capitole sau navigare prin înregistrare. Pentru video lung sau YouTube, folosește capabilitatea separată venice-video, prin /video/transcriptions, care primește direct un URL public de video. Această capabilitate este pentru fișiere audio încărcate ca fișier.

Nu încărca audio pe care nu ai dreptul să îl procesezi. Dacă înregistrarea conține persoane, date personale, informații medicale, financiare, contractuale sau conversații private, trateaz-o ca upload către un serviciu extern și obține aprobarea necesară înainte. Transcriptul poate păstra informații sensibile aproape perfect. O unealtă de transcriere nu devine brusc un preot cu jurământ de tăcere.

Pentru indexul general: All guides.

Cum îl invoc / declanșez

Nu există un trigger conversațional universal garantat. Invocarea depinde de runtime-ul în care este instalată capabilitatea. La nivel API, cererea minimă este:

curl https://api.venice.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "file=@./meeting.m4a" \
  -F "model=nvidia/parakeet-tdt-0.6b-v3" \
  -F "response_format=json" \
  -F "timestamps=false"

Prerechizite:

  • cheie Venice validă în VENICE_API_KEY;
  • acces la endpoint, inclusiv eventuală disponibilitate Pro;
  • balanță suficientă;
  • fișier audio local, real, sub limita de mărime;
  • permisiune să transcrii și să trimiți acel audio către Venice.

Câmpuri utile:

  • file: obligatoriu, fișier audio în multipart. Nu JSON, nu base64.
  • model: default nvidia/parakeet-tdt-0.6b-v3.
  • response_format: documentat ca json sau text; pentru timings folosește o formă care păstrează timestamps.
  • timestamps: false implicit; activează timpii când formatul de răspuns îi poate conține.
  • language: hint ISO 639-1, de exemplu en sau ja; doar modelele din familia Whisper îl respectă.

Exemplu practic

Ai o înregistrare meeting.m4a și vrei transcript JSON:

curl https://api.venice.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "file=@./meeting.m4a" \
  -F "model=openai/whisper-large-v3" \
  -F "response_format=json" \
  -F "language=en" \
  -F "timestamps=false"

Răspuns posibil:

{ "text": "Alright everyone, let's kick off the meeting..." }

Pentru timestamps:

-F "timestamps=true"

Păstrează un format care poate include timpi. Schema exactă pentru segmente sau cuvinte este dependentă de model.

Output / unde aterizează

Output-ul vine în răspunsul API.

Cu response_format=json, primești un obiect care conține cel puțin text. Cu timestamps=true, răspunsul poate include timing pe segmente sau cuvinte, în funcție de model și forma răspunsului.

Cu response_format=text, primești text/plain: doar transcriptul, fără metadata. Dacă ai nevoie de timing, nu cere text simplu. Folosește o formă de răspuns potrivită pentru timestamps, cum ar fi JSON extins sau format de subtitrare, dacă runtime-ul/API-ul o acceptă.

Capabilitatea nu promite automat salvare în fișiere, note, baze de date sau indexuri de căutare. Dacă vrei persistență, trebuie făcută explicit de client sau de runtime.

Limite / gotchas

Dimensiunea maximă a fișierului este 25 MB. Dacă o depășești, endpoint-ul întoarce 400 cu mesaj de tip "Maximum size is 25MB", nu 413.

Venice nu oferă chunking nativ aici. Pentru fișiere mai lungi, împarte client-side, de exemplu cu ffmpeg:

ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3

Apoi transcrii fiecare chunk și lipești rezultatele, ajustând offset-urile pentru timestamps.

Erori importante:

  • 400: parametri greșiți, format nesuportat, fișier gol sau peste 25 MB.
  • 401: autentificare invalidă sau acces Pro necesar.
  • 402: balanță insuficientă.
  • 415: Content-Type greșit; trebuie multipart/form-data.
  • 422: validare, eroare upstream ASR sau respingere de content policy.
  • 429: rate limit; folosește backoff.
  • 500 / 503: tranzient; retry cu jitter.

Pentru batch-uri mari, limitează paralelismul la aproximativ 5 cereri și tratează 429 ca semnal de încetinire, nu ca invitație la ciocănit mai tare în ușă.

Graph View