# Importuoti YouTube vaizdo įrašą

> Įtraukia YouTube vaizdo įrašą į transkribavimo eilę ir prideda jį į jūsų biblioteką.

Šaltinis: https://diko.app/api-docs/zinynas/create-library-import

Importai · `POST /library/imports`

- **Bazinis URL:** https://api.diko.app/api/v1
- **Reikalingas leidimas:** `library:write`
- **Ribų politika:** `write`, `imports`, `account`
- **Autentifikacija:** `Authorization: Bearer dk_live_...`

Užklausa niekada nelaukia transkribavimo pabaigos. Tikrinkite `GET /library/imports/{import_id}` (arba prenumeruokite įvykius `library.import.*`), kol `status` taps `succeeded`, `failed` arba `canceled`.

* Jei vaizdo įrašas jau yra jūsų bibliotekoje arba Diko jį jau transkribavo, atsakymas yra `201` su `reused: true`, o kreditai nenaudojami. Tai vis tiek importas: jis įskaitomas į paros ribą.
* Jei to paties vaizdo įrašo importas dar vyksta, atsakymas yra `200` su tuo importu.
* Kitu atveju atsakymas yra `201` su antrašte `Location`. Kreditai tikrinami dabar ir dar kartą prieš mokamą darbą. Jei eilėje per daug importų arba pasiekta paros riba, atsakymas yra `429 queue_limit_exceeded` (`error.details.limit` nurodo, kuri riba).
* Vaizdo įrašas be subtitrų transkribuojamas kalbos atpažinimu bendroje Diko eilėje. Tie darbai naudoja tas pačias naudotojo transkribavimo vietas kaip jūsų įkėlimai programėlėje, bet niekada nepaima paskutinės laisvos vietos. Ji lieka jūsų įkėlimams ir įrašams. Darbas gali laukti laisvos vietos; tuo metu importas lieka `queued` arba `processing`.
* Atšaukus, išjungus ar ištrynus API raktą, kuris sukūrė importą, rotavus jį be persidengimo arba atšaukus raktą dėl nutekėjimo, to rakto importai, kurie dar eilėje ar vykdomi, atšaukiami. Sustabdžius API prieigą, taip pat atšaukiami visos paskyros importai. Importas eilėje iškart tampa `canceled`, vykdomas tampa `canceling` ir sustojus darbui baigiasi kaip `canceled` (įvykis `library.import.canceled`). Rotacija su persidengimu importų nesustabdo. Jau atliktas darbas apmokestinamas kaip įprasta.

Siųskite antraštę `Idempotency-Key`, kad pakartojimas būtų saugus.

## Parametrai

| Pavadinimas | Vieta | Tipas | Privalomas | Numatytoji reikšmė | Apribojimai | Aprašas |
|---|---|---|---|---|---|---|
| `Idempotency-Key` | header | `string` | ne | – | 8–255 simbolių; pattern: ^[A-Za-z0-9_\-:.]{8,255}$ | Padaro pakartojimą saugų: tas pats raktas su ta pačia užklausa grąžina pirmąjį atsakymą (`Idempotent-Replayed: true`); kita užklausa su tuo pačiu raktu atmetama su 422 `idempotency_key_reused`. 8–255 simboliai iš A-Z a-z 0-9 _ - : . Saugomas 24 val. |

## Užklausos turinys

Importuotinas vaizdo įrašas. Turinio tipas: `application/json`.

- `url` (string, privalomas, 1–2048 simbolių): YouTube vaizdo įrašo nuoroda (youtube.com, www.youtube.com, m.youtube.com, music.youtube.com arba youtu.be).
- `language` (string | null, neprivalomas): Užuomina subtitrų kalbai ir kalbos atpažinimui. Praleiskite, kad būtų naudojama jūsų numatytoji Diko kalba. Galimos reikšmės: `lt`, `en`.

```json
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "lt"
}
```

## Atsakymas

### 201

Importas sukurtas (`queued`) arba transkripcija jau egzistavo (`succeeded` su `reused: true`).

- `Idempotent-Replayed`: `true`, kai atsakymas yra ankstesnės užklausos su tuo pačiu `Idempotency-Key` pakartojimas.
- `Location`: Sukurto importo URL.
- `RateLimit`: Labiausiai ribojanti taikyta politika: `"pavadinimas";r=<liko užklausų>;t=<sekundės>`. `t` – sekundės iki kitos leidžiamos užklausos (0, kai talpa pilna). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `RateLimit-Policy`: Užklausai taikytos ribų politikos, po vieną elementą `"pavadinimas";q=<pradinė talpa>;w=<sekundės>` kiekvienai, pavyzdžiui, `"read";q=10;w=2, "account";q=20;w=2`: `q` – pradinė talpa, `w` – sekundės, per kurias tuščia talpa vėl prisipildo. Siunčiama su kiekvienu autentifikuotu atsakymu; nesiunčiama, kai užklausai ribotuvas netaikytas, pavyzdžiui, kai ji atmesta dar nepatikrinus rakto.
- `Request-Id`: Šios užklausos ID (priešdėlis `req_`), toks pat kaip `request_id` klaidos atsakyme. Siunčiamas ir kaip `X-Request-ID`. Kreipdamiesi pagalbos nurodykite jį.
- `X-Client-Request-Id`: Jūsų siųsta užklausos antraštė `X-Client-Request-Id`, grąžinta atgal. Grąžinama tik tada, kai jūsų reikšmė turi 1–128 simbolius iš A-Z a-z 0-9 . _ : -.
- `X-RateLimit-Limit`: Labiausiai ribojančios politikos pradinė talpa (`q` antraštėje `RateLimit-Policy`). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `X-RateLimit-Remaining`: Labiausiai ribojančioje politikoje likusios užklausos (`r` antraštėje `RateLimit`). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `X-RateLimit-Reset`: Sekundės iki kitos leidžiamos užklausos labiausiai ribojančioje politikoje (`t` antraštėje `RateLimit`; 0, kai talpa pilna). Tai sekundžių skaičius, o ne laiko žyma. Nesiunčiama, kai užklausai ribotuvas netaikytas.

Turinio tipas: `application/json`

- `id` (string, privalomas, 26–26 simbolių, pattern: ^imp_[0-9A-Za-z]{22}$): Viešas importo ID (priešdėlis `imp_`).
- `object` (string, privalomas): Visada `library_import`.
- `status` (string, privalomas): Importo būsena. Galimos reikšmės: `queued`, `processing`, `canceling`, `succeeded`, `failed`, `canceled`.
- `stage` (string | null, privalomas): Dabartinis etapas; tik kai `processing`. Galimos reikšmės: `captions`, `waiting`, `downloading`, `transcribing`, `summarizing`.
- `queue_position` (integer | null, privalomas, 1–2147483647, format: int32): Vieta tarp jūsų eilėje esančių importų (1 = kitas); `null`, kai importas nėra `queued`.
- `url` (string, privalomas, format: uri): Kanoninis YouTube URL.
- `youtube_video_id` (string, privalomas): YouTube vaizdo įrašo ID.
- `language` (string | null, privalomas): Išsiųsta kalbos užuomina arba `null`. Galimos reikšmės: `lt`, `en`.
- `reused` (boolean, privalomas): `true`, kai vaizdo įrašas jau buvo jūsų bibliotekoje arba bendroje Diko talpykloje, todėl kreditai nenaudoti.
- `transcript_id` (string | null, privalomas, 6–64 simbolių, pattern: ^trn_[A-Za-z0-9_-]+$): Bibliotekos transkripcijos ID (priešdėlis `trn_`), kai importas `succeeded`; kitaip `null`.
- `error` (object | null, privalomas): Klaidos duomenys, kai importas `failed`; kitaip `null`.
  - `code` (string, privalomas): Stabilus klaidos kodas. Nežinomi vidiniai kodai pateikiami kaip `internal_error`. Galimos reikšmės: `video_unavailable`, `video_private`, `age_restricted`, `video_too_long`, `video_duration_unknown`, `captions_unavailable`, `download_failed`, `transcription_failed`, `transcription_timeout`, `provider_limit`, `insufficient_credits`, `internal_error`.
  - `message` (string, privalomas): Paaiškinimas `Accept-Language` kalba.
- `created_at` (string, privalomas, ≤ 24 simbolių, format: date-time): Kada importas sukurtas.
- `updated_at` (string, privalomas, ≤ 24 simbolių, format: date-time): Kada importas paskutinį kartą pasikeitė.
- `completed_at` (string | null, privalomas, ≤ 24 simbolių, format: date-time): Kada importas pasiekė galutinę būseną; kitaip `null`.

```json
{
  "id": "imp_6Mfj7Oxm4MfxGGmZRhiUQf",
  "object": "library_import",
  "status": "queued",
  "stage": null,
  "queue_position": 1,
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "youtube_video_id": "dQw4w9WgXcQ",
  "language": "lt",
  "reused": false,
  "transcript_id": null,
  "error": null,
  "created_at": "2026-10-11T09:30:00.000Z",
  "updated_at": "2026-10-11T09:30:00.100Z",
  "completed_at": null
}
```

### 200

To paties vaizdo įrašo importas jau vyksta; grąžinamas esamas importas.

- `Content-Location`: Esamo importo, kurį aprašo šis atsakymas, URL.
- `Idempotent-Replayed`: `true`, kai atsakymas yra ankstesnės užklausos su tuo pačiu `Idempotency-Key` pakartojimas.
- `RateLimit`: Labiausiai ribojanti taikyta politika: `"pavadinimas";r=<liko užklausų>;t=<sekundės>`. `t` – sekundės iki kitos leidžiamos užklausos (0, kai talpa pilna). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `RateLimit-Policy`: Užklausai taikytos ribų politikos, po vieną elementą `"pavadinimas";q=<pradinė talpa>;w=<sekundės>` kiekvienai, pavyzdžiui, `"read";q=10;w=2, "account";q=20;w=2`: `q` – pradinė talpa, `w` – sekundės, per kurias tuščia talpa vėl prisipildo. Siunčiama su kiekvienu autentifikuotu atsakymu; nesiunčiama, kai užklausai ribotuvas netaikytas, pavyzdžiui, kai ji atmesta dar nepatikrinus rakto.
- `Request-Id`: Šios užklausos ID (priešdėlis `req_`), toks pat kaip `request_id` klaidos atsakyme. Siunčiamas ir kaip `X-Request-ID`. Kreipdamiesi pagalbos nurodykite jį.
- `X-Client-Request-Id`: Jūsų siųsta užklausos antraštė `X-Client-Request-Id`, grąžinta atgal. Grąžinama tik tada, kai jūsų reikšmė turi 1–128 simbolius iš A-Z a-z 0-9 . _ : -.
- `X-RateLimit-Limit`: Labiausiai ribojančios politikos pradinė talpa (`q` antraštėje `RateLimit-Policy`). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `X-RateLimit-Remaining`: Labiausiai ribojančioje politikoje likusios užklausos (`r` antraštėje `RateLimit`). Nesiunčiama, kai užklausai ribotuvas netaikytas.
- `X-RateLimit-Reset`: Sekundės iki kitos leidžiamos užklausos labiausiai ribojančioje politikoje (`t` antraštėje `RateLimit`; 0, kai talpa pilna). Tai sekundžių skaičius, o ne laiko žyma. Nesiunčiama, kai užklausai ribotuvas netaikytas.

Turinio tipas: `application/json`

- `id` (string, privalomas, 26–26 simbolių, pattern: ^imp_[0-9A-Za-z]{22}$): Viešas importo ID (priešdėlis `imp_`).
- `object` (string, privalomas): Visada `library_import`.
- `status` (string, privalomas): Importo būsena. Galimos reikšmės: `queued`, `processing`, `canceling`, `succeeded`, `failed`, `canceled`.
- `stage` (string | null, privalomas): Dabartinis etapas; tik kai `processing`. Galimos reikšmės: `captions`, `waiting`, `downloading`, `transcribing`, `summarizing`.
- `queue_position` (integer | null, privalomas, 1–2147483647, format: int32): Vieta tarp jūsų eilėje esančių importų (1 = kitas); `null`, kai importas nėra `queued`.
- `url` (string, privalomas, format: uri): Kanoninis YouTube URL.
- `youtube_video_id` (string, privalomas): YouTube vaizdo įrašo ID.
- `language` (string | null, privalomas): Išsiųsta kalbos užuomina arba `null`. Galimos reikšmės: `lt`, `en`.
- `reused` (boolean, privalomas): `true`, kai vaizdo įrašas jau buvo jūsų bibliotekoje arba bendroje Diko talpykloje, todėl kreditai nenaudoti.
- `transcript_id` (string | null, privalomas, 6–64 simbolių, pattern: ^trn_[A-Za-z0-9_-]+$): Bibliotekos transkripcijos ID (priešdėlis `trn_`), kai importas `succeeded`; kitaip `null`.
- `error` (object | null, privalomas): Klaidos duomenys, kai importas `failed`; kitaip `null`.
  - `code` (string, privalomas): Stabilus klaidos kodas. Nežinomi vidiniai kodai pateikiami kaip `internal_error`. Galimos reikšmės: `video_unavailable`, `video_private`, `age_restricted`, `video_too_long`, `video_duration_unknown`, `captions_unavailable`, `download_failed`, `transcription_failed`, `transcription_timeout`, `provider_limit`, `insufficient_credits`, `internal_error`.
  - `message` (string, privalomas): Paaiškinimas `Accept-Language` kalba.
- `created_at` (string, privalomas, ≤ 24 simbolių, format: date-time): Kada importas sukurtas.
- `updated_at` (string, privalomas, ≤ 24 simbolių, format: date-time): Kada importas paskutinį kartą pasikeitė.
- `completed_at` (string | null, privalomas, ≤ 24 simbolių, format: date-time): Kada importas pasiekė galutinę būseną; kitaip `null`.

```json
{
  "id": "imp_6Mfj7Oxm4MfxGGmZRhiUQf",
  "object": "library_import",
  "status": "queued",
  "stage": null,
  "queue_position": 1,
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "youtube_video_id": "dQw4w9WgXcQ",
  "language": "lt",
  "reused": false,
  "transcript_id": null,
  "error": null,
  "created_at": "2026-10-11T09:30:00.000Z",
  "updated_at": "2026-10-11T09:30:00.100Z",
  "completed_at": null
}
```

## Pavyzdžiai

**cURL**

```bash
curl -X POST "https://api.diko.app/api/v1/library/imports" \
  -H "Authorization: Bearer $DIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","language":"lt"}'
```

**Python**

```python
import os
import uuid

import requests

response = requests.post(
    "https://api.diko.app/api/v1/library/imports",
    headers={
        "Authorization": f"Bearer {os.environ['DIKO_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # create once per operation, reuse on retries
    },
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "language": "lt",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.diko.app/api/v1/library/imports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DIKO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // create once per operation, reuse on retries
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    language: "lt",
  }),
})
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`)
console.log(await response.json())
```

## Klaidos

Šis endpointas gali grąžinti šias klaidas. Visų kodų aprašai yra klaidų kataloge.

| HTTP | Kodas | Reikšmė | Kartoti? |
|---|---|---|---|
| 400 | [`invalid_request`](https://diko.app/api-docs/klaidos.md#invalid_request) | Užklausa neatitinka formato: užklausos turinys nėra tinkamas JSON, jo nėra, jis nėra JSON objektas arba `Content-Length` nėra skaičius. Trūkstamas privalomas laukas ar nežinomas laukas yra `invalid_parameter`. | ne |
| 400 | [`invalid_parameter`](https://diko.app/api-docs/klaidos.md#invalid_parameter) | Kelio, užklausos ar turinio parametro reikšmė netinkama, privalomo lauko trūksta arba laukas nežinomas (nežinomi laukai atmetami). Lauke `error.param` nurodytas parametras. | ne |
| 400 | [`invalid_youtube_url`](https://diko.app/api-docs/klaidos.md#invalid_youtube_url) | URL nėra palaikomas vieno YouTube vaizdo įrašo adresas. | ne |
| 400 | [`idempotency_key_invalid`](https://diko.app/api-docs/klaidos.md#idempotency_key_invalid) | `Idempotency-Key` netinkamas: reikia 8–255 simbolių iš aibės `A-Z a-z 0-9 _ - : .`. | ne |
| 401 | [`missing_api_key`](https://diko.app/api-docs/klaidos.md#missing_api_key) | Užklausoje nėra antraštės `Authorization`. | ne |
| 401 | [`invalid_api_key`](https://diko.app/api-docs/klaidos.md#invalid_api_key) | Antraštė netinkama (ne `Bearer` schema, tuščias raktas arba kelios antraštės `Authorization`) arba raktas nežinomas ar blogo formato (neatitinka struktūros ar kontrolinės sumos). Atsakymas visais šiais atvejais vienodas. | ne |
| 401 | [`api_key_expired`](https://diko.app/api-docs/klaidos.md#api_key_expired) | Rakto galiojimas pasibaigė. | ne |
| 401 | [`api_key_revoked`](https://diko.app/api-docs/klaidos.md#api_key_revoked) | Raktas atšauktas: rankiniu būdu, pasibaigus rotacijos persidengimui, dėl nutekėjimo arba išjungus paskyrą. | ne |
| 401 | [`api_key_disabled`](https://diko.app/api-docs/klaidos.md#api_key_disabled) | Raktas laikinai išjungtas. | ne |
| 402 | [`subscription_required`](https://diko.app/api-docs/klaidos.md#subscription_required) | Paskyra neturi aktyvios apmokėtos prieigos. | ne |
| 402 | [`insufficient_credits`](https://diko.app/api-docs/klaidos.md#insufficient_credits) | Importui nepakanka kreditų. | ne |
| 402 | [`team_member_limit_reached`](https://diko.app/api-docs/klaidos.md#team_member_limit_reached) | Pasiekta jūsų kreditų riba komandoje. | ne |
| 403 | [`ip_not_allowed`](https://diko.app/api-docs/klaidos.md#ip_not_allowed) | Raktas turi IP apribojimą, o užklausos IP nėra sąraše arba jo nepavyksta nustatyti patikimai. | ne |
| 403 | [`account_disabled`](https://diko.app/api-docs/klaidos.md#account_disabled) | Paskyra išjungta. | ne |
| 403 | [`email_not_verified`](https://diko.app/api-docs/klaidos.md#email_not_verified) | Paskyros el. paštas nepatvirtintas. | ne |
| 403 | [`api_access_suspended`](https://diko.app/api-docs/klaidos.md#api_access_suspended) | Diko administratorius sustabdė šios paskyros API prieigą. | ne |
| 403 | [`plan_required`](https://diko.app/api-docs/klaidos.md#plan_required) | Planas neapima API. `error.details.required_plans` yra `verslas`. | ne |
| 403 | [`insufficient_scope`](https://diko.app/api-docs/klaidos.md#insufficient_scope) | Raktas neturi endpointui reikalingo leidimo. `error.details` turi `required_scopes` ir `granted_scopes`. | ne |
| 403 | [`team_member_disabled`](https://diko.app/api-docs/klaidos.md#team_member_disabled) | Jūsų narystė komandoje išjungta. | ne |
| 408 | [`request_timeout`](https://diko.app/api-docs/klaidos.md#request_timeout) | Užklausos turinys nebuvo gautas per ribotą laiką (numatyta 10 s). Taip nutinka, kai klientas siunčia turinį per lėtai arba sustoja per siuntimą. Nieko nesukurta. | taip |
| 409 | [`idempotency_in_progress`](https://diko.app/api-docs/klaidos.md#idempotency_in_progress) | Ta pati užklausa su tuo pačiu `Idempotency-Key` dar vykdoma. | taip, po Retry-After |
| 413 | [`request_too_large`](https://diko.app/api-docs/klaidos.md#request_too_large) | Užklausos turinys didesnis nei 64 KB. | ne |
| 415 | [`unsupported_media_type`](https://diko.app/api-docs/klaidos.md#unsupported_media_type) | POST užklausos turinys turi būti `application/json`. | ne |
| 422 | [`idempotency_key_reused`](https://diko.app/api-docs/klaidos.md#idempotency_key_reused) | Tas pats `Idempotency-Key` panaudotas su kitu metodu, keliu ar turiniu. | ne |
| 429 | [`queue_limit_exceeded`](https://diko.app/api-docs/klaidos.md#queue_limit_exceeded) | Pasiekta importų talpa: iki 10 aktyvių vienam naudotojui, 200 iš viso arba 500 per parą. | taip, po Retry-After |
| 429 | [`rate_limit_exceeded`](https://diko.app/api-docs/klaidos.md#rate_limit_exceeded) | Viršyta ribų politika. `error.details.policy` nurodo, kuri. | taip, po Retry-After |
| 500 | [`internal_error`](https://diko.app/api-docs/klaidos.md#internal_error) | Vidinė serverio klaida. | sąlygiškai |
| 503 | [`credit_balance_unavailable`](https://diko.app/api-docs/klaidos.md#credit_balance_unavailable) | Kreditų likučio dabar nepavyko nustatyti, todėl importas nepradėtas. | taip, po Retry-After |
| 503 | [`writes_disabled`](https://diko.app/api-docs/klaidos.md#writes_disabled) | Rašymo operacijos laikinai išjungtos platformos pusėje. Skaitymas veikia. | taip, po Retry-After |
| 503 | [`service_unavailable`](https://diko.app/api-docs/klaidos.md#service_unavailable) | Paslauga laikinai užimta, pavyzdžiui, dėl duomenų bazės apkrovos. | taip, po Retry-After |