Inwistan API on täälläMuunna mikä tahansa tallenne transkripteiksi, lähetysvalmiiksi tekstityksiksi ja käännöksiksi — suoraan omista järjestelmistäsi.

API-referenssi

Litteroi, paranna ja käännä tekstityksiä ohjelmallisesti. Perus-URL, autentikointi, jokainen päätepiste ja jokainen virhekoodi — kaikki yhdellä sivulla.

Siirry osioon…

Base URL: https://api.inwista.ai/v1

Autentikointi

Luo API-avain kohdassa Dashboard → API Keys (vain työtilan ylläpitäjät). Avain näytetään vain kerran — säilytä se kuin salasana.

Lähetä avain jokaisen pyynnön mukana Bearer-tokenina. Avaimet on rajattu yhteen työtilaan: kaikki, mitä API palauttaa, kuuluu siihen. API:n kautta luodut resurssit näkyvät hallintapaneelissa, mutta hallintapaneelin projektit eivät näy API:n kautta.

Jokainen autentikointivirhe — puuttuva otsake, tuntematon avain, mitätöity avain — palauttaa saman 401-vastauksen.

curl https://api.inwista.ai/v1/transcriptions \
  -H "Authorization: Bearer inw_live_4f6a…"

Virheet

Jokainen virhe käyttää samaa kuorirakennetta: objektia, jossa on koneluettava koodi ja ihmisluettava viesti. V1:n sisällä koodeja ainoastaan lisätään — rakenna toimintasi koodin, älä viestin varaan.

{ "error": { "code": "insufficient_credits", "message": "…" } }

Status	Koodi	Milloin
401	invalid_api_key	Autentikointi epäonnistui (mistä tahansa syystä)
400	invalid_source_url	Ei https, tunnistetietoja URL-osoitteessa, yksityinen isäntä tai virheellinen muoto
400	invalid_language	Puuttuu tai ei ole ISO 639-1 -koodi
400	invalid_num_speakers	Ei kokonaisluku välillä 1–32
400	invalid_store_media	Ei totuusarvo
400	invalid_retention	Ei "standard" tai "none", tai yhdistetty arvoon store_media true
400	invalid_metadata	Ei objekti tai yli 1 KB
400	invalid_settings	Ei objekti tai yli 2 KB
400	unreadable_source	Median kestoa ei voitu määrittää
400	invalid_cursor	starting_after ei ole tunnettu id
400	invalid_format	Tekstitysmuotoa ei tueta
402	insufficient_credits	Saldo ei riitä kattamaan kustannusta
404	not_found	Tuntematon resurssi
404	translation_not_found	Pyydetylle kielelle ei ole valmista käännöstä toimitettavalle versiolle
409	not_ready	Edellyttää valmistunutta litterointia
409	operation_in_progress	Parannus on vielä käynnissä
409	translation_exists	Kieli on jo olemassa tälle versiolle
400	invalid_idempotency_key	Idempotency-Key-otsake on tyhjä tai yli 255 merkkiä
400	idempotency_key_reused	Idempotency-Key on jo käytetty eri pyyntöön
409	idempotency_conflict	Tällä avaimella tehtyä pyyntöä käsitellään yhä
429	rate_limited	Liikaa pyyntöjä — yritä uudelleen Retry-After-otsakkeen mukaan

Idempotenssi

Jokainen POST-kutsu veloittaa krediittejä hyväksynnän yhteydessä, joten aikakatkaistun pyynnön sokea uudelleenyritys loisi toisen työn ja toisen veloituksen. Lähetä Idempotency-Key-otsake (mikä tahansa yksilöllinen merkkijono, enintään 255 merkkiä), niin uudelleenyritykset ovat turvallisia: ensimmäisen pyynnön vastaus tallennetaan 24 tunniksi ja palautetaan muuttumattomana jokaiselle samalla avaimella tehdylle uudelleenyritykselle.

Avaimen uudelleenkäyttö eri pyynnön kanssa palauttaa 400 idempotency_key_reused; uudelleenyritys alkuperäisen ollessa vielä käynnissä palauttaa 409 idempotency_conflict. Virhevastauksia ei koskaan tallenneta — epäonnistunut pyyntö ei koskaan pidä veloitusta, joten avain vapautuu puhtaalle uudelleenyritykselle.

curl -X POST https://api.inwista.ai/v1/transcriptions \
  -H "Authorization: Bearer inw_live_…" \
  -H "Idempotency-Key: order-42-transcribe" \
  -H "Content-Type: application/json" \
  -d '{ "source_url": "…", "language": "en" }'

Kutsurajat

Kukin API-avain saa tehdä 300 lukupyyntöä (GET) ja 60 kirjoituspyyntöä (POST) minuutissa. Kiintiö täyttyy jatkuvasti, ja sen voi käyttää kerralla. Rajan ylittyessä API vastaa 429 rate_limited ja Retry-After-otsakkeella (sekunteina).

Pidä lukuja suuntaa-antavina: hidasta saadessasi 429 ja suosi webhookeja tiheän pollauksen sijaan.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": { "code": "rate_limited", "message": "…" } }

Krediitit

Operaatiot mitataan krediitteinä työtilasi ennakkoon ladatusta saldosta (lataa lisää kohdassa Dashboard → Billing). Litterointi maksaa 4 krediittiä jokaiselta alkavalta mediaminuutilta. Parannus ja kääntäminen hinnoitellaan sisällön koon mukaan — samoilla hinnoilla, jotka Studio veloittaa. Nouto, listaus ja tilan kysely ovat maksuttomia.

Veloitus tapahtuu, kun pyyntö hyväksytään. Jos operaatio epäonnistuu, veloitus hyvitetään automaattisesti ja resurssi näyttää credits_charged: 0. 402-hylkäys ei koskaan veloita mitään.

Sivutus

Listapäätepisteet hyväksyvät parametrit limit (oletus 25, enintään 100) ja starting_after — edellisen sivun viimeinen id. Vastaukset käärivät tulokset list-objektiin, jossa on has_more.

{ "object": "list", "data": [ … ], "has_more": true }

Litteroinnit

Lähetä media URL-osoitteena, pollaa kunnes tila on completed (tai käytä webhookeja) ja nouda sitten tekstitykset. Tilat ovat processing, completed ja failed. Aikaleimat ovat unix-sekunteja.

Pollaus ja tulokset käyttävät samaa päätepistettä: GET /v1/transcriptions/{id} on sekä paikka, jossa seuraat tilaa, ETTÄ paikka, jossa valmis resurssi sijaitsee — erillistä tulospäätepistettä ei ole. Ainoa poikkeus ovat itse tekstitystiedostot, jotka tulevat aina tekstityspäätepisteestä, koska ne ovat raakoja tiedostorunkoja, eivät JSONia.

Luo litterointi

POST/v1/transcriptions

Muunna mikä tahansa verkossa isännöity mediatiedosto tarkoiksi, aikaleimatuiksi tekstityksiksi ilman, että kenenkään tarvitsee avata Studiota — syötä tulokset suoraan CMS:ääsi, arkistoosi tai julkaisuputkeesi.

Median kesto tarkistetaan ennen pyynnön hyväksymistä; saldo veloitetaan ja työ lisätään jonoon yhtenä atomisena vaiheena. Palauttaa 201 ja litterointiresurssin.

Krediitit: 4 krediittiä jokaiselta alkavalta mediaminuutilta, veloitetaan kun työ hyväksytään. Epäonnistuneet työt hyvitetään automaattisesti.

Runko

Kenttä	Tyyppi	Kuvaus
`source_url`pakollinen	string	Mediatiedoston julkinen https-URL tai YouTube-/TikTok-/Vimeo-URL
`language`pakollinen	string	ISO 639-1 -koodi, esim. "en" tai "nb-NO"
`diarization`	boolean	Puhujamerkinnät (oletus false)
`num_speakers`	integer	1–32, vihje puhujantunnistukselle
`store_media`	boolean	false = vain transkriptio: toistotiedostoja ei valmistella (oletus true)
`retention`	string	"none" poistaa lähdemedian transkription jälkeen — transkriptio säilyy (oletus "standard")
`metadata`	object	Omat tunnisteesi, enintään 1 KB, palautetaan sellaisenaan

curl -X POST https://api.inwista.ai/v1/transcriptions \
  -H "Authorization: Bearer inw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/interview.mp4",
    "language": "en",
    "diarization": true
  }'

Vastaus

{
  "id": "aB3dE9f2…",
  "object": "transcription",
  "status": "processing",
  "progress": 50,
  "language": "en",
  "duration_seconds": 1834,
  "diarization": true,
  "store_media": true,
  "retention": "standard",
  "source_url": "https://cdn.example.com/interview.mp4",
  "metadata": { "internal_ref": "case-42" },
  "credits_charged": 124,
  "error": null,
  "created": 1754558000
}

Listaa litteroinnit

GET/v1/transcriptions

Täsmäytä katalogisi käsiteltyihin töihin tai rakenna hallintanäkymä kaiken litteroimasi päälle.

API:n kautta luodut litteroinnit, uusimmat ensin. Vakiosivutus.

Krediitit: Maksuton.

Kyselyparametrit

Kenttä	Tyyppi	Kuvaus
`limit`	integer	Sivun koko, oletus 25, enintään 100
`starting_after`	string	Kursori: edellisen sivun viimeinen id

curl "https://api.inwista.ai/v1/transcriptions?limit=10" \
  -H "Authorization: Bearer inw_live_…"

Hae litterointi

GET/v1/transcriptions/{id}

Sekä edistymisen seuranta että lopputulos: seuraa, kun tila vaihtuu arvoon completed, ja lue sitten kesto, kieli ja veloitus samasta vastauksesta.

Pollaa, kunnes tila on completed (tai rekisteröi webhook, katso alla). Epäonnistuneen litteroinnin lukeminen käynnistää myös sen automaattisen hyvityksen.

Krediitit: Maksuton.

curl https://api.inwista.ai/v1/transcriptions/aB3dE9f2… \
  -H "Authorization: Bearer inw_live_…"

Vastaus

{
  "id": "aB3dE9f2…",
  "object": "transcription",
  "status": "processing",
  "progress": 50,
  "language": "en",
  "duration_seconds": 1834,
  "diarization": true,
  "store_media": true,
  "retention": "standard",
  "source_url": "https://cdn.example.com/interview.mp4",
  "metadata": { "internal_ref": "case-42" },
  "credits_charged": 124,
  "error": null,
  "created": 1754558000
}

Poista transkriptio

DELETE/v1/transcriptions/{id}

Poista työ pyynnöstä — täysi hallinta omiin tietoihin yhdellä kutsulla.

Poistaa transkription pysyvästi kaikkine tallennettuine tietoineen: mediatiedostot, transkription sisällön, versiot, käännökset ja kommentit. Koostetut laskutuslaskurit säilyvät — ne eivät sisällä sisältöä.

Vain valmiit tai epäonnistuneet työt voi poistaa; yhä käsittelyssä oleva työ palauttaa 409, samoin työ, jolla on kesken oleva parannus tai käännös. Poisto on välitön eikä sitä voi perua.

Krediitit: endpoints.delete-transcription.pricing

curl -X DELETE https://api.inwista.ai/v1/transcriptions/aB3dE9f2… \
  -H "Authorization: Bearer inw_live_…"

Vastaus

{
  "id": "aB3dE9f2…",
  "object": "transcription",
  "deleted": true
}

Nouda tekstitykset

GET/v1/transcriptions/{id}/captions

Vedä lähetysvalmiit tekstitystiedostot suoraan soittimeesi, MAM-järjestelmääsi tai jakeluputkeesi — ei manuaalisia vientejä, ei muotomuunnoksia omassa päässäsi. Videotuotantoputkessa valmis SRT tai VTT putoaa suoraan leikkausohjelmaasi, katselmointityökaluusi tai paketointivaiheeseen heti, kun leikkaus on litteroitu.

Palauttaa raa'an tekstitystiedoston rungon vastaavalla Content-Type-otsakkeella — ei JSON-käärittynä. Vastaa 409 not_ready, kunnes litterointi on valmis.

Krediitit: Maksuton.

Kyselyparametrit

Kenttä	Tyyppi	Kuvaus
`format`pakollinen	string	srt, vtt, json tai txt
`diarization`	"true"	Lisää puhujamerkinnät etuliitteeksi
`language`	string	Palauta valmistunut käännös lähteen sijaan; 404 translation_not_found jos sitä ei ole toimitettavalle versiolle
`revision`	string	Hae tietty versio (parannuksen id on sen revision id); ilman parametria = uusin

curl "https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/captions?format=srt" \
  -H "Authorization: Bearer inw_live_…" -o interview.srt

json-muoto on versioitu sopimus: { version: 1, language, segments: [{ index, start, end, text, speaker? }] } — sekunteja millisekunnin tarkkuudella, ja version sisällä kenttiä ainoastaan lisätään.

Käännökset kuuluvat siihen versioon, jota varten ne luotiin — käännösresurssin revision_id nimeää sen, eikä myöhemmän parannuksen versio peri niitä. Käytä tätä revision_id-arvoa revision-parametrina noutaaksesi käännetyn version.

Parannukset

Tekoälypohjainen tekstitysten parannus — rivipituudet, tasapainotus ja ajoitussäännöt — joka tuottaa tekstityksistä uuden version. Edellyttää valmistunutta litterointia. Kun parannus valmistuu, tekstitysten nouto palauttaa parannetun version automaattisesti.

Käynnistä parannus

POST/v1/transcriptions/{id}/enhance

Lähetystason ajoitus ja rivien tasapainotus automaattiohjauksella — toimita tekstitykset, jotka läpäisevät laaduntarkastuksen ilman, että editoija koskee niihin. Tuotantoyhtiöille tämä automatisoi toimitusputken tekstitysten viimeistelyvaiheen: jokainen jakso lähtee talosta yhdenmukaisin, vaatimusten mukaisin tekstityksin.

Palauttaa 202 ja parannusresurssin.

Krediitit: Lasketaan tekstityssisällön koosta samalla hinnalla, jonka Studio veloittaa, ja vähennetään, kun työ hyväksytään. Hyvitetään automaattisesti epäonnistuessa.

Runko

Kenttä	Tyyppi	Kuvaus
`settings`	object	Studion parannusasetukset, enintään 2 KB; jätä pois, niin käytetään oletuksia

Parannuksen asetukset

Kenttä	Tyyppi	Kuvaus
`maxLinesPerBlock`	"1" \| "2"	Kerralla näytettävien rivien määrä; lähetysstandardi ja oletus on 2
`maxCharactersPerLine`	1–100	Merkkejä riviä kohden; lähetysstandardi ja oletus on 42
`blockLineBalancing`	bottom_heavy \| top_heavy \| equal \| unconstrained	Kaksirivisten lohkojen visuaalinen muoto; oletus on unconstrained
`textCondensation`	none \| smart \| aggressive	Antaa tekoälyn tiivistää liian nopeasti luettavaa dialogia; oletus on none (sanatarkka)
`speakerDialogueFormat`	none \| hyphens \| speaker_name \| brackets	Miten saman lohkon useat puhujat erotetaan; oletus on none
`continuationMarkers`	none \| end \| start \| both	Merkin sijoitus, kun virke jatkuu usean lohkon yli; oletus on none
`continuationMarkerStyle`	dash \| ellipsis	Ajatusviiva tai ellipsi jaetuille virkkeille; oletus on dash
`gapBetweenBlocks`	none \| broadcasting \| streaming \| sdh	Pakotettu tyhjä väli peräkkäisten lohkojen välillä; oletus on broadcasting (~99 ms)
`minBlockDuration`	0.1–60 s	Lyhin aika, jonka lohko näkyy ruudulla, sekunneissa; oletus on 1.0
`maxBlockDuration`	> min	Pisin aika, jonka lohko näkyy ruudulla, sekunneissa; oletus on 7.0

curl -X POST https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/enhance \
  -H "Authorization: Bearer inw_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "maxCharactersPerLine": 37, "textCondensation": "smart" } }'

Vastaus

{
  "id": "rev8Xk3…",
  "object": "enhancement",
  "transcription_id": "aB3dE9f2…",
  "status": "processing",
  "progress": 0,
  "credits_charged": 12,
  "error": null,
  "created": 1754559000
}

Hae parannus

GET/v1/transcriptions/{id}/enhancements/{enhancementId}

Tilakysely ja tulos yhdessä: kun tila on completed, tekstityspäätepiste palauttaa jo parannetun version.

Pollaa, kunnes tila on completed. Epäonnistuneen parannuksen lukeminen käynnistää sen automaattisen hyvityksen.

Krediitit: Maksuton.

curl https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/enhancements/rev8Xk3… \
  -H "Authorization: Bearer inw_live_…"

Käännökset

Tekstitysten kääntäminen niin, että ajoitus periytyy lähteestä — yksi käännös kieltä ja tekstitysversiota kohden. Edellyttää valmistunutta litterointia.

Käynnistä käännös

POST/v1/transcriptions/{id}/translate

Yksi kutsu kieltä kohden muuttaa valmiin tekstitysraidan lokalisoiduksi versioksi identtisellä ajoituksella — moninkertaista jokaisen jo olemassa olevan videosi tavoittavuus.

Palauttaa 202. Vastaa 409 translation_exists, jos kieli on jo olemassa nykyiselle versiolle.

Krediitit: Lasketaan tekstityssisällön koosta samalla hinnalla, jonka Studio veloittaa, kohdekieltä kohden; vähennetään hyväksynnän yhteydessä. Hyvitetään automaattisesti epäonnistuessa.

Runko

Kenttä	Tyyppi	Kuvaus
`target_language`pakollinen	string	ISO 639-1 -koodi, esim. "es"
`target_label`	string	Näyttönimi, enintään 60 merkkiä

curl -X POST https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/translate \
  -H "Authorization: Bearer inw_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "target_language": "es" }'

Vastaus

{
  "id": "es",
  "object": "translation",
  "transcription_id": "aB3dE9f2…",
  "target_language": "es",
  "revision_id": "TRkf2nY7…",
  "status": "processing",
  "progress": 0,
  "credits_charged": 6,
  "error": null,
  "created": 1754559600
}

Hae käännös

GET/v1/transcriptions/{id}/translations/{language}

Tilakysely ja tulos yhdessä: kun tila on completed, nouda käännetty tekstitystiedosto tekstityspäätepisteestä language-parametrilla.

Pollaa, kunnes tila on completed, ja nouda sitten käännetyt tekstitykset tekstityspäätepisteestä language-kyselyparametrilla.

Krediitit: Maksuton.

# Poll the translation resource
curl https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/translations/es \
  -H "Authorization: Bearer inw_live_…"

# Once completed, fetch the translated subtitle file
curl "https://api.inwista.ai/v1/transcriptions/aB3dE9f2…/captions?format=vtt&language=es" \
  -H "Authorization: Bearer inw_live_…" -o interview-es.vtt

Webhookit

Määritä webhook kohdassa Dashboard → Integrations → Webhook, niin saat transcript.completed-tapahtumat pollauksen sijaan. Hyötykuormat allekirjoitetaan HMAC-SHA256:lla (X-Inwista-Signature: sha256=<hex> raa'asta rungosta) allekirjoitussalaisuudella, joka näytetään kerran määrityksen yhteydessä. Tiedostojen URL-osoitteet ovat esiallekirjoitettuja ja vanhenevat 24 tunnin kuluttua.

{
  "event": "transcript.completed",
  "id": "evt_9f2c…",
  "timestamp": 1754560000,
  "workspaceId": "ws_…",
  "project": {
    "id": "aB3dE9f2…",
    "name": "interview.mp4",
    "language": "en",
    "durationSeconds": 1834
  },
  "files": [
    {
      "format": "srt",
      "name": "interview.srt",
      "mimeType": "application/x-subrip; charset=utf-8",
      "url": "https://…",
      "expiresAt": 1754646400
    }
  ]
}

Arvostamme yksityisyyttäsi

Käytämme evästeitä ymmärtääksemme, miten Inwistaa käytetään, ja mitataksemme mainontaamme. Tietosuojaseloste · Evästekäytäntö