Հայերեն խոսքի ճանաչման API. սղագրեք հայերեն ձայնագրությունները cURL-ի, Python-ի և Node.js-ի միջոցով

Ինչպե՞ս ավելացնել հայերեն խոսքի ճանաչում ձեր հավելվածին#

Ուղարկեք աուդիո կամ վիդեո ֆայլը hispeech.ai API-ին ձեր API բանալիի հետ միասին, և արդյունքում հայերեն տեքստը կստանաք JSON ֆորմատով։ API-ն ունի երեք մուտքային կետ, որոնք բոլորն էլ օգտագործում են նույն միավորները և նույն հայերեն մոդելները․

1. Ստացեք API բանալի#

Գրանցվեք app.hispeech.ai կայքում և բացեք «Կարգավորումներ» բաժինը՝ API բանալի ստեղծելու համար։ Պահպանեք այն միայն սերվերի կողմում և երբեք մի ներառեք բջջային հավելվածի կամ վեբ էջի կոդի մեջ։ Ստորև բերված օրինակները բանալին կարդում են HISPEECH_API_KEY միջավայրի փոփոխականից (environment variable):

2. Սղագրեք ֆայլը (սինխրոն ռեժիմով)#

Ամենապարզ հարցումը․ ուղարկեք ֆայլը և միանգամից ստացեք սղագրության արդյունքը նույն պատասխանում։

cURL

curl --location 'https://api.hispeech.ai/api/v1/transcriptions/upload' \
  --header "x-auth-token: $HISPEECH_API_KEY" \
  --form 'file=@"interview.mp3"' \
  --form 'wait_for_result="true"'

Python

import os
import requests

API_KEY = os.environ["HISPEECH_API_KEY"]

with open("interview.mp3", "rb") as f:
    r = requests.post(
        "https://api.hispeech.ai/api/v1/transcriptions/upload",
        headers={"x-auth-token": API_KEY},
        files={"file": f},
        data={"wait_for_result": "true"},
        timeout=600,
    )
r.raise_for_status()
print(r.json()["transcription"])

Node.js (18+)

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("interview.mp3")]), "interview.mp3");
form.append("wait_for_result", "true");

const res = await fetch("https://api.hispeech.ai/api/v1/transcriptions/upload", {
  method: "POST",
  headers: { "x-auth-token": process.env.HISPEECH_API_KEY },
  body: form,
});
const data = await res.json();
console.log(data.transcription);

Պատասխանն իրենից ներկայացնում է JSON՝ տեքստով և վայրկյաններով արտահայտված ձայնագրության տևողությամբ․

{
  "job_id": "a91f17d0-5d9a-11f1-8d6f-215414e3f380",
  "success": true,
  "secure_mode": false,
  "transcription": "Խոսում է, գրում է, պատմում է, ասում է։",
  "audio_duration": 3
}

3. Երկար ձայնագրություններ (ասինխրոն ռեժիմ)#

Դասախոսությունների, հանդիպումների կամ փոդքասթների դեպքում ուղարկեք առաջադրանքը (job) և ստացեք արդյունքը մի փոքր ուշ։ Կարգավիճակի ստուգումները սահմանափակված են ժամում առավելագույնը 60 հարցումով, ուստի խորհուրդ է տրվում ստուգել մոտավորապես րոպեն մեկ անգամ։

Python

import os
import time
import requests

BASE = "https://api.hispeech.ai/api/v1/transcriptions"
HEADERS = {"x-auth-token": os.environ["HISPEECH_API_KEY"]}

with open("lecture.mp4", "rb") as f:
    job = requests.post(f"{BASE}/upload", headers=HEADERS,
                        files={"file": f}, data={"wait_for_result": "false"}).json()

job_id = job["job_id"]
while True:
    time.sleep(60)  # at most 60 status checks per hour
    s = requests.get(f"{BASE}/transcription-status/{job_id}", headers=HEADERS).json()
    if s["status"] == "completed":
        print(s["transcription"])
        break
    if s["status"] != "processing":
        raise RuntimeError(s)

Ստանդարտ ռեժիմում ձայնագրությունն ու սղագրությունը պահպանվում են ձեր հաշվեկշռում այնքան ժամանակ, քանի դեռ դրանք չեք ջնջել DELETE /api/v1/transcriptions հարցման միջոցով՝ փոխանցելով {"transcription_id": "JOB_ID"} մարմինը (body):

4. Օգտագործեք OpenAI SDK-ն (OpenAI-համատեղելի վերջնակետ)#

Եթե ձեր կոդն արդեն օգտագործում է OpenAI-ը սղագրության համար, կարող եք այն հարմարեցնել հայերենի համար՝ պարզապես փոխելով հիմնական URL-ն (base URL) ու API բանալին: model պարամետրում սահմանեք hispeech.ai մոդելի նույնացուցիչը (ID)՝ model-01052025 (Հիմնական) կամ model-23012026 (Փորձնական): OpenAI-ի մոդելների անունները, ինչպիսին է whisper-1-ը, չեն ընդունվում:

Python (openai)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HISPEECH_API_KEY"],
    base_url="https://api.hispeech.ai/api/v1",
)

with open("voice-note.m4a", "rb") as f:
    result = client.audio.transcriptions.create(model="model-01052025", file=f)

print(result.text)

Node.js (openai)

import fs from "node:fs";
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.HISPEECH_API_KEY,
  baseURL: "https://api.hispeech.ai/api/v1",
});

const result = await openai.audio.transcriptions.create({
  file: fs.createReadStream("voice-note.m4a"),
  model: "model-01052025", // or "model-23012026" (Conversational)
});
console.log(result.text);

Այն գործիքները, որոնք պահանջում են միայն բազային URL (առանց /v1), որպես արժեք ընդունում են https://api.hispeech.ai/api հասցեն։

5. Ի՞նչ է վերադարձնում API-ն#

Վերբեռնման և կարգավիճակի ստուգման վերջնակետերը (endpoints) վերադարձնում են JSON պատասխան։ Ստորև ներկայացված են API-ի փաստաթղթերում նշված դաշտերը․

OpenAI-համատեղելի վերջնակետը (endpoint) վերադարձնում է OpenAI-ի ֆորմատով JSON՝ text, duration, language, task և հատվածների (segments) ցանկ, որոնցից յուրաքանչյուրն ունի սկզբի (start) և ավարտի (end) ժամանակները՝ վայրկյաններով։

6. Ո՞ր մոդելն օգտագործել#

Փաստաթղթերի և ենթագրերի համար օգտագործեք Հիմնական (Formal) մոդելը, իսկ բառացի սղագրությունների համար՝ Փորձնական (Conversational) մոդելը։ Ընտրեք դրանցից մեկը վերբեռնման վերջնակետի stt_model հարցման պարամետրի միջոցով․

• model-01052025․ Հիմնական (լռելյայն)։ Մաքուր գրական հայերեն, լավագույնն է փաստաթղթերի և ենթագրերի համար։ Այն կարող է ոչ պաշտոնական խոսքը վերածել ստանդարտ գրավոր ձևի։
• model-23012026․ Փորձնական։ Գրում է հենց այն, ինչ լսում է, ներառյալ այնպիսի խոսակցական ձևեր, ինչպիսին է «ասում ա»-ն։ Այն լավագույնն է բառացի սղագրությունների և զանգերի վերլուծության համար։

curl --location 'https://api.hispeech.ai/api/v1/transcriptions/upload?stt_model=model-23012026' \
  --header "x-auth-token: $HISPEECH_API_KEY" \
  --form 'file=@"call.wav"' \
  --form 'wait_for_result="true"'

OpenAI-համատեղելի վերջնակետում փոխարենը նույն մոդելի ID-ն փոխանցեք model դաշտի միջոցով։

7. Ինչպե՞ս սղագրել կոնֆիդենցիալ (զգայուն) ինֆորմացիա պարունակող ձայնագրությունն առանց այն պահպանելու#

Վերբեռնման հարցմանը ավելացրեք secure_mode=true պարամետրը։ Օգտագործեք այն բժշկական, իրավական կամ այլ զգայուն ձայնագրությունների համար։ Սերվերում որևէ բան չի պահպանվում․ սինխրոն ռեժիմում դուք ստանում եք տեքստը, և այն անմիջապես ջնջվում է, իսկ ասինխրոն ռեժիմում արդյունքը պահվում է միայն հիշողության մեջ՝ մինչև այն մեկ անգամ կարդաք կամ մինչև պահպանման ժամկետի (TTL) սպառվելը։ ttl-ը կարող եք սահմանել վայրկյաններով՝ 1-ից մինչև 36,000 (լռելյայն արժեքն է 900, այսինքն՝ 15 րոպե)։

curl --location 'https://api.hispeech.ai/api/v1/transcriptions/upload' \
  --header "x-auth-token: $HISPEECH_API_KEY" \
  --form 'file=@"patient-note.m4a"' \
  --form 'wait_for_result="false"' \
  --form 'secure_mode="true"' \
  --form 'ttl="900"'

8. Ի՞նչ ֆորմատներ և սահմանափակումներ են կիրառվում#

• Ֆորմատներ․ MP3, WAV, M4A, AAC, FLAC, OGG, OPUS, AIFF, WMA, AMR և այլ աուդիո ֆորմատներ, ինչպես նաև MP4, MOV, MKV, WEBM, 3GP, M4V և այլ տեսանյութերի ֆորմատներ։
• Չափս․ մինչև 10 ԳԲ և 10 ժամ տևողությամբ մեկ ֆայլի համար։
• Արագություն․ մոտ 20 վայրկյան՝ մեկ ժամ տևողությամբ ձայնագրության համար։
• Լեզու․ հայերեն, նախատեսված արևելահայերենի համար։
• Կարգավիճակի ստուգումներ․ ժամում առավելագույնը 60 անգամ։
• Ներառված չէ․ ենթագրերի ֆայլեր և ենթագրերով տեսանյութեր (դրանց համար օգտագործեք համապատասխան հավելվածները)։

9. Որքա՞ն արժե հայերեն խոսքի API-ն#

API-ի օգտագործումն արժե 1 միավոր ձայնագրության յուրաքանչյուր վայրկյանի համար։ Վճարովի փաթեթները սկսվում են ամսական $3.99 (1,590 ֏)-ից, իսկ Business ծավալները հասնում են մինչև 36,000,000 միավորի (մանրամասները՝ սակագների բաժնում)։ Ստարտա՞փ կամ անհատական նախագիծ եք ստեղծում։ Գրեք info@hispeech.ai հասցեին և տեղեկացեք անվճար միավորների մասին։

Բոլոր պարամետրերի և պատասխանների ամբողջական ուղեցույցը հասանելի է API-ի փաստաթղթերում։ Այնտեղ առկա է նաև «Copy for AI» կոճակը, որը պատճենում է ամբողջ ուղեցույցը, որպեսզի կարողանաք այն տեղադրել ChatGPT-ում, Claude-ում կամ Gemini-ում և գեներացնել ձեր տեխնոլոգիական ստեկին համապատասխան ինտեգրման կոդը։

Հաճախ տրվող հարցեր

Արդյո՞ք գոյություն ունի API հայերեն խոսքից տեքստի (speech-to-text) համար։

Այո՛։ hispeech.ai-ն առաջարկում է REST API հայերեն խոսքի ճանաչման համար api.hispeech.ai հասցեում՝ սինխրոն, ասինխրոն և OpenAI-համատեղելի վերջնակետերով (endpoints): Ամբողջական ուղեցույցը հասանելի է hispeech.ai/api.html էջում։

Կարո՞ղ եմ օգտագործել OpenAI SDK-ն հայերեն սղագրությունների համար։

Այո՛։ OpenAI-ի պաշտոնական SDK-ում որպես base URL սահմանեք https://api.hispeech.ai/api/v1 հասցեն, օգտագործեք ձեր hispeech.ai API բանալին և կանչեք audio.transcriptions.create ֆունկցիան՝ նշելով model="model-01052025" (Հիմնական) կամ model="model-23012026" (Փորձնական)։

Կարո՞ղ է API-ն ստեղծել SRT ենթագրեր։

Այս պահին՝ ոչ։ API-ն վերադարձնում է տեքստային սղագրություններ։ Ենթագրերի ֆայլերը (.SRT / .ASS) և ենթագրված տեսանյութերը հասանելի են hispeech.ai-ի վեբ, բջջային և համակարգչային հավելվածներում։

Որքա՞ն արժե հայերեն խոսքի API-ն։

1 միավոր՝ ձայնագրության յուրաքանչյուր վայրկյանի համար (3,600 միավոր՝ մեկ ժամվա համար)։ Գոյություն ունի օրական անվճար սահմանաչափ, վճարովի փաթեթները սկսվում են ամսական $3.99 (1,590 ֏)-ից, իսկ ստարտափներն ու անհատ ծրագրավորողները կարող են դիմել անվճար API միավորներ ստանալու համար։

Ի՞նչ է վերադարձնում հայերեն խոսքի API-ն։

Վերբեռնման վերջնակետը (endpoint) վերադարձնում է JSON պատասխան՝ job_id, success, transcription տեքստով և վայրկյաններով արտահայտված audio_duration արժեքով։ OpenAI-համատեղելի վերջնակետը վերադարձնում է OpenAI-ի ֆորմատը՝ text, duration և հատվածների (segments) ցանկ՝ սկզբի ու ավարտի ժամանակներով։

Վերադարձնո՞ւմ է արդյոք API-ն ժամանակային նշումներ (timestamps)։

OpenAI-համատեղելի վերջնակետը (endpoint) վերադարձնում է հատվածներ (segments), որոնցից յուրաքանչյուրն ունի վայրկյաններով արտահայտված սկզբնական ու ավարտական ժամանակները և համապատասխան տեքստը։ Վերբեռնման վերջնակետը վերադարձնում է ամբողջական սղագրությունը և ձայնագրության տևողությունը։ Պատրաստի ենթագրերի ֆայլեր ստանալու համար օգտագործեք hispeech.ai հավելվածները։

Աշխատո՞ւմ է API-ն արևմտահայերենով։

Մոդելները նախատեսված են արևելահայերենի համար։ Արևմտահայերենը նույնպես կարող է սղագրվել, սակայն նկատելիորեն ավելի շատ սխալներով, ուստի նախապես փորձարկեք այն ձեր սեփական ձայնագրությամբ։

Ի՞նչ աուդիո ֆորմատներ է ընդունում API-ն։

Տարածված աուդիո և տեսանյութերի ֆորմատներ, այդ թվում՝ MP3, WAV, M4A, AAC, FLAC, OGG, OPUS, AMR, MP4, MOV, MKV և WEBM՝ մինչև 10 ԳԲ ծավալով և մեկ ֆայլի համար 10 ժամ տևողությամբ։