API videon litterointiin ja muistiinpanoihin

Pika-aloitus

Näillä vaiheilla tiedosto kulkee levyltäsi litteroinniksi ja muistiinpanoiksi. Tarvitset aktiivisen Basic- tai Plus-tilauksen, päätteen ja esimerkkiasiakasta varten Python 3.12:n tai uudemman.

1. Luo API-avain

Kirjaudu sivustolle (esimerkiksi hintasivulla), avaa tilipalkista API-avaimet, nimeä avain ja aseta halutessasi vanhenemispäivä. Kopioi salaisuus heti, kun se tulee näkyviin: se näytetään vain kerran. Enintään kolme avainta voi olla aktiivisena samaan aikaan.

2. Tallenna avain ympäristömuuttujaan

Pidä avain poissa lähdekoodista, komentoriviargumenteista ja lokeista. Esimerkit lukevat avaimen muuttujasta VTN_API_KEY ja perus-URL:n muuttujasta VTN_API_BASE.

export VTN_API_BASE="https://api.video-to-notes.com"
read -rs VTN_API_KEY && export VTN_API_KEY   # paste the key, press Enter

$env:VTN_API_BASE = "https://api.video-to-notes.com"
$env:VTN_API_KEY = Read-Host "API key" -MaskInput

3. Tarkista tilisi

Tämä kutsu vahvistaa, että avain toimii, ja palauttaa tilauksesi, jäljellä olevat tilaussekuntisi, tuetut muodot ja nykyiset rajat.

# Sends the key through stdin, so it never appears in the process list.
vtn() {
  printf 'header = "Authorization: Bearer %s"\n' "$VTN_API_KEY" |
    curl -s --config - "$@"
}

vtn "$VTN_API_BASE/api/v1/account"

$headers = @{ Authorization = "Bearer $env:VTN_API_KEY" }
Invoke-RestMethod "$env:VTN_API_BASE/api/v1/account" -Headers $headers |
  ConvertTo-Json -Depth 5

4. Litteroi tiedosto

Lataa Python-esimerkkiasiakas. Se tarvitsee vain vakiokirjaston. Se lähettää tiedoston osina, käynnistää työn, odottaa sen valmistumista ja tallentaa jokaisen tulossivun.

python client.py run meeting.mp4 --state meeting.state.json \
  --output meeting.jsonl --download meeting-files

Jos haluat käsitellä vain osan tallenteesta, lisää --start ja --end sekunteina tiedoston alusta. --audio-language antaa kielivihjeen ja --notes-language valitsee muistiinpanojen kielen. Ilman näitä valintoja koko tiedosto käsitellään ja kielet tunnistetaan automaattisesti.

python client.py run lecture.webm --state lecture.state.json \
  --start 30 --end 3630 --audio-language ru --notes-language en

Tilatiedosto tallentaa latauksen tunnisteen ja pyynnön identiteetin, ei koskaan avainta. Jos komento keskeytyy, aja se uudelleen samalla tilatiedostolla: se löytää saman työn, eikä sinulta veloiteta kahdesti. Käytä jokaiselle uudelle työlle uutta tilatiedostoa.

5. Lue tulokset

meeting.jsonl sisältää yhden JSON-tulossivun riviä kohden: litterointitekstin aikoineen, muistiinpanot Markdown-muodossa, aukot ja varoitukset. meeting-files sisältää lataukset, kuten litteroinnin TXT-muodossa ja muistiinpanot Markdown-, HTML- ja PDF-muodossa. Asiakkaassa on myös nämä komennot:

python client.py account
python client.py status JOB_ID
python client.py result JOB_ID --output results.jsonl --download files
python client.py cancel JOB_ID
python client.py resume JOB_ID

Käytätkö mieluummin curlia? Bash-pika-aloitus tekee samat lataus-, työ- ja tulosvaiheet curlilla ja jq:lla.

bash quickstart.sh meeting.mp4

Näin työ etenee

Jokainen integraatio etenee samojen kuuden vaiheen kautta. API-viite näyttää jokaisen kutsun esimerkkipyynnön ja -vastauksen kanssa.

1. Tarkista tili. GET /api/v1/account palauttaa tilauksesi, jäljellä olevat sekunnit, tuetut muodot ja rajat.
2. Luo lataus. POST /api/v1/uploads tiedoston koolla tavuina ja tiedostopäätteellä. Vastaus kertoo osien koon ja määrän.
3. Lähetä osat. Hae allekirjoitetut URL-osoitteet kutsulla POST /api/v1/uploads/{upload_id}/parts, lähetä jokainen osa HTTP-PUT-pyynnöllä suoraan tallennustilaan, säilytä jokainen ETag ja kutsu sitten POST /api/v1/uploads/{upload_id}/complete.
4. Käynnistä työ. POST /api/v1/jobs latauksen tunnisteella ja Idempotency-Key-otsakkeella. Palvelin tarkistaa todellisen tiedoston, suunnittelee työn ja varaa ajan tilauksestasi.
5. Kysy tilaa. GET /api/v1/jobs/{job_id}, kunnes tila on lopullinen, ja odota kutsujen välillä vähintään poll_after_seconds.
6. Lue tulos. GET /api/v1/jobs/{job_id}/result ja seuraa next_cursor-arvoa, kunnes se on null. Lataa artifacts-kentän tiedostot ennen kuin niiden linkit vanhenevat.

Työ päättyy tilaan completed, completed_with_gaps, interrupted, cancelled, failed tai expired. charged_seconds näyttää, kuinka paljon työ käytti tilaustasi.

Hyvät käytännöt

Nämä tavat suojaavat avaimesi, estävät kaksinkertaiset veloitukset ja tekevät pitkistä töistä luotettavia.

Pidä avaimet salassa

• Kutsu APIa vain palvelimelta tai skriptistä, jota hallitset itse. Älä koskaan laita avainta selainkoodiin, mobiilisovellukseen, URL-osoitteeseen tai versionhallintaan.
• Lataa avain ympäristömuuttujasta tai salaisuuksien hallinnasta ja pidä se poissa lokeista, virheraporteista ja komentoriviargumenteista.
• Käytä yhtä avainta integraatiota kohden ja anna sille vanhenemispäivä, jotta voit vaihtaa tai perua yhden avaimen koskematta muihin.
• Kun vaihdat avaimen, luo uusi, ota se käyttöön ja peru sitten vanha. Jo käynnistyneet työt jatkuvat.
• Jos avain on voinut vuotaa esimerkiksi keskusteluun, tikettiin tai committiin, peru se heti API-avaimet-paneelissa.

Tee töiden luomisesta turvallisesti toistettavaa

• Luo jokaiselle uudelle työlle satunnainen Idempotency-Key, esimerkiksi UUID, ja tallenna se latauksen tunnisteen kanssa ennen kuin lähetät pyynnön.
• Jos vastaus katoaa, lähetä sama pyyntö samalla avaimella uudelleen. Saat alkuperäisen työn takaisin, eikä sinulta veloiteta kahdesti.
• Älä koskaan käytä avainta uudelleen toiselle tiedostolle tai toisille valinnoille: API vastaa silloin 409 IDEMPOTENCY_CONFLICT.

Kysy maltillisesti ja huomioi rajat

• Odota tilakyselyjen välillä vähintään viisi sekuntia, ja pidempään, jos poll_after_seconds sitä pyytää.
• Kun saat 429- tai 503-vastauksen, odota Retry-After-otsakkeen tai error.retry_after_seconds-arvon mukaan ja yritä sitten uudelleen pienellä satunnaisella viiveellä.
• Toista pyyntö muuttamattomana vain, jos error.retryable on true. Muuten korjaa ensin pyyntö.
• Tili suorittaa yhden latauksen ja yhden työn kerrallaan. Laita tiedostosi jonoon ja lähetä seuraava, kun nykyinen työ on valmis.

Hallitse käyttämiäsi tunteja

• Tarkista remaining_seconds ennen lataamista. Työ, joka tarvitsee enemmän aikaa kuin sinulla on, epäonnistuu virheellä INSUFFICIENT_BALANCE; API ei koskaan lyhennä valintaasi, jotta se mahtuisi.
• Lähetä range, kun tarvitset vain osan tallenteesta. Vain valitusta äänestä veloitetaan.
• Peru työt, joita et enää tarvitse. Valmiit osat säilyvät saatavilla ja käyttämätön varattu aika palautetaan.
• Keskeytä lataukset, joita et aio käyttää, jotta seuraava lataus voi alkaa.

Kerää täydelliset tulokset

• Seuraa next_cursor-arvoa, kunnes se on null. Sivulla on enintään 32 kohdetta.
• Käsittele gap-kohteita ääninä, joita ei voitu käsitellä, ei hiljaisuutena, ja tarkista warnings.
• Lataa artifacts-kentän tiedostot, kun niiden linkit ovat voimassa (enintään kymmenen minuuttia); hae sivu uudelleen saadaksesi uudet linkit.
• Tallenna tarvitsemasi: tulostiedostoja säilytetään noin 24 tuntia ja litteroinnin palautusta noin 48 tuntia.
• Lue tarvitsemasi kentät ja ohita loput.

Usein kysytyt kysymykset

Tiedostot ja esimerkit

Esimerkit ja sopimustiedostot julkaistaan sivuston mukana, ja ne vastaavat tuotannossa olevaa APIa.

• client.py: esimerkkiasiakas Python 3.12+:lle, vain vakiokirjasto
• quickstart.sh: Bash-esimerkki curlilla ja jq:lla
• openapi.json: OpenAPI 3.1 -kuvaus jokaisesta päätepisteestä esimerkkeineen
• paid-api.schema.json: JSON Schema jokaisesta pyynnöstä ja vastauksesta

Apua

Onko jokin epäselvää tai eikö jokin toimi? Ota yhteyttä ja kerro virhevastauksen request_id, kellonaika ja päätepiste. Älä koskaan lähetä meille API-avaintasi.