Joburi de transcriere și traducere

Înlocuiește SERVICE de mai jos cu speech_to_text sau translate, iar JOB_ID cu UUID-ul primit. Toate operațiunile necesită datele de autentificare ale contului tău, conform secțiunii Autentificare, și sunt limitate la contul proprietar. Poți citi un job de pe oricare dintre cele două gazde API, însă fiecare folosește propria structură de răspuns; folosește consecvent aceeași gazdă.

Pe api.multitel.net, erorile de autentificare (401) sunt returnate înainte de aplicarea acestei structuri și pot avea un alt corp de răspuns. Verifică mai întâi codul de stare HTTP.

Autentificare

Fiecare cerere trebuie să conțină datele de autentificare ale contului tău. Joburile, cheile de idempotență, limitele, consumul și costurile aparțin contului care deține datele de autentificare. Ele sunt comune tuturor credențialelor acelui cont, pe ambele gazde, indiferent de credențialele folosite pentru cerere.

• HTTP Basic (Authorization: Basic, sau curl --user). Sunt acceptate un cont API de tip parolă, un subcont sau datele de conectare ale contului tău. Recomandăm un cont API dedicat. Numele de utilizator nu poate conține două puncte, iar numele de utilizator și parola nu pot fi goale.
• Token Bearer (Authorization: Bearer YOUR_TOKEN). Acceptat pentru un cont API de tip token. Conturile API de tip token trebuie să aibă o restricție IP, iar cererile trebuie să provină de la o adresă permisă. Ambele gazde API acceptă adresele IPv4 și intervalele CIDR configurate pentru cont. Un token nu poate fi trimis ca parolă Basic. Verifică dacă tokenul funcționează pe gazda folosită.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Dacă un cont API are restricții după adresa IP, trimite cererile de la o adresă permisă. Datele de autentificare lipsă sau nevalide returnează 401. Pe api.multitel.net, datele valide care nu pot folosi aceste servicii, de exemplu credențialele unui cont de tip token trimise prin Basic, returnează 403 unsupported_transcription_principal sau unsupported_translation_principal. Încercările repetate de autentificare nereușite de la aceeași adresă pe api.multitel.net pot duce la blocarea adresei. Corectează datele de autentificare înainte de a reîncerca.

Verifică periodic finalizarea

Trimite o cerere GET /v3/SERVICE/JOB_ID. Recomandăm să verifici cel mult o dată la 3 secunde. Structura exterioară descrie cererea; verifică valoarea status din obiectul jobului pentru a afla dacă procesarea s-a încheiat.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Pe api.multitel.net, setează HOST la https://api.multitel.net și citește .response.id în loc de .data.id.

Reîncearcă în siguranță cererile cu rezultat incert

Dacă o cerere de creare expiră sau returnează 429 ori un cod 5xx, retrimite aceleași date cu aceeași cheie de idempotență. Răspunsul oricărei gazde se poate pierde sau poate fi înlocuit cu o eroare după acceptarea lucrării; retrimiterea aceleiași chei returnează jobul, dacă există. Refolosirea unei chei cu alte date returnează 409 idempotency_conflict. Unele erori se repetă la fiecare încercare, precum 503 când un serviciu cu plată este dezactivat sau 500 pentru un fișier audio care nu poate fi citit. Oprește-te după câteva încercări.

Schimbarea cheii are efecte diferite pentru fiecare serviciu.

• Pentru transcrierea audio, o cheie nouă creează un job nou, taxat separat dacă procesarea reușește. Cheia inițială continuă să returneze jobul inițial, chiar și după actualizarea procesării.
• Pentru traducere, o cheie nouă cu același conținut returnează fără cost suplimentar un job corespunzător aflat în așteptare, în procesare, finalizat sau în așteptarea plății. Creează o lucrare nouă dacă jobul anterior a eșuat sau versiunea de procesare s-a schimbat. Reîncercarea traducerii cu cheia inițială returnează 409 după schimbarea versiunii de procesare; păstrează ID-ul jobului inițial și citește direct jobul.

Obține rezultatul după alimentarea contului

Pentru un job în starea awaiting_payment, alimentează contul astfel încât soldul să fie cel puțin egal cu costUsd al jobului, rotunjit în sus la următorul multiplu de $0.00001, apoi trimite POST /v3/SERVICE/JOB_ID/settle. Debitările se fac în pași întregi de $0.00001 și includ restul reportat de la joburile anterioare ale aceluiași serviciu. Suma debitată poate astfel depăși costUsd cu mai puțin de $0.00001. Pe api.multi.tel, trimite JSON {} sau un corp gol; orice proprietate din corp este respinsă cu 400. api.multitel.net ignoră corpul cererii. Achitarea eliberează rezultatul salvat fără a relua transcrierea sau traducerea. Răspunsul conține jobul; verifică dacă starea sa este completed. Dacă soldul este în continuare insuficient, jobul rămâne în starea awaiting_payment, iar răspunsul are în continuare codul HTTP 200.

Pentru transcrierea audio, achitarea unui job deja finalizat îl returnează cu duplicate: true, iar achitarea unui job în așteptare, în procesare sau eșuat returnează 409 transcription_not_awaiting_payment. Pentru traducere, achitarea unui job aflat în orice altă stare returnează jobul neschimbat. Achitarea este disponibilă numai cât timp procesarea cu plată este activată (altfel returnează 503). Joburile în așteptarea plății sunt incluse în costul rezervat; pentru conturile preplătite, ele pot bloca cererile noi cu plată printr-un răspuns 402 până când sunt achitate.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Verifică utilizarea

Folosește GET /v3/SERVICE/usage. Parametrii opționali from și to sunt date UTC în formatul YYYY-MM-DD, iar ambele date de la capetele intervalului sunt incluse. Dacă nu sunt specificați, from este implicit data de acum 30 de zile, iar to este implicit data de astăzi (UTC). to nu trebuie să fie anterioară datei from, iar diferența dintre date poate fi de cel mult 366 de zile (până la 367 de date incluse). Datele calendaristice nevalide și intervalele inversate sau mai lungi returnează 400, la fel ca alți parametri de interogare pe api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Răspunsul conține mode, currency (USD), from, to și days, o listă ordonată de la cele mai recente înregistrări.

• Înregistrările pentru transcrierea audio sunt grupate după dată și sursă. Ele conțin date, source (api, sau hpbx pentru înregistrări Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd și debitedUsd.
• Înregistrările pentru traducere sunt grupate după dată, sursă și motor. Ele conțin date, source, engine, jobs, sourceCharacters, accruedUsd și debitedUsd.

accruedUsd este costul exact cu nouă zecimale, iar debitedUsd este suma debitată, cu cinci zecimale. Utilizarea se înregistrează la data UTC la care s-a achitat costul fiecărui job; joburile în așteptare, în procesare, eșuate și în așteptarea plății nu apar.

Limite

Fiecare cont poate avea cel mult 50 de joburi de transcriere audio și traducere nefinalizate în total: în așteptare, în procesare sau în așteptarea plății, inclusiv cele pentru înregistrări Hosted PBX. Când se atinge această limită sau capacitatea totală a serviciului, cererile de creare returnează 429 transcription_queue_full sau translation_queue_full. api.multi.tel limitează, de asemenea, fiecare adresă IP client la 300 de cereri pe minut pentru toate cererile către acea gazdă. La atingerea limitei, răspunsul este 429, cu antete de limitare a ratei și corp text simplu, în locul structurii JSON pentru erori.

Gestionează erorile cererilor

Pe gazda principală, erorile returnează un cod de stare HTTP de eroare și JSON cu status: "error", code, message și requestId. Fiecare răspuns include și un antet X-Request-ID. Poți furniza propria valoare; valorile mai lungi de 128 de caractere sunt trunchiate. Gazda de compatibilitate returnează numai codul erorii în response.code. Înregistrează ID-ul cererii, când este disponibil, și codul erorii, dar nu include audio, text sau date de autentificare în jurnale.

Coduri de stare frecvente:

Urmează codul de eroare returnat; nu presupune că toate erorile de validare au același cod de stare.

Pentru 429 sau 503, așteaptă și reîncearcă la intervale progresiv mai mari, cu aceeași cheie de creare; respectă Retry-After când este prezent. Pentru date de intrare sau autentificare nevalide, corectează mai întâi cauza. Nu trimite repetat chei noi cât timp joburile anterioare sunt încă în așteptare.