Import a YouTube video into the library

Required scope

library:write

Authentication

Authorization: Bearer

Rate-limit policy

writeimportsaccount

The request never waits for the transcription: poll GET /library/imports/{import_id} (or subscribe to the library.import.* events) until status is succeeded, failed or canceled.

* A video already in your library, or already transcribed by Diko, answers 201 with reused: true and costs no credits. It is still an import: it counts toward the daily limit. * An import of the same video that is still running answers 200 with that import. * Otherwise 201 with a Location header. Credits are checked now and again before paid work; when too many imports are queued, or the daily limit is reached, the answer is 429 queue_limit_exceeded (error.details.limit says which limit). * A video without captions is transcribed by speech recognition in Diko's shared queue. Those jobs use the same per-user transcription slots as your own uploads in the app, but never the last free one (it stays available for your uploads and recordings), and may wait for a free slot; the import stays queued or processing meanwhile. * Revoking, disabling or deleting the API key that created an import, rotating it without an overlap period, or a revocation because of a leak cancels that key's imports that are still queued or running, and suspending API access does the same for the whole account: a queued import ends canceled at once, a running one becomes canceling and ends canceled when the work stops (event library.import.canceled). A rotation with a grace period leaves them running. Work already done is charged as usual.

Send an Idempotency-Key header to make retries safe.

Parameters

Request body

The video to import.

Content type: application/json

• urlstringrequired

  A YouTube video link (youtube.com, www.youtube.com, m.youtube.com, music.youtube.com or youtu.be).

  1–2048 characters

• languagestring | null

  Hint for the caption language and speech recognition. Omit to use your Diko default language.

  Allowed values: lten

Response

Examples

Request

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"}'

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())

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())

Example response · 201 · application/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
}

Example response · 200 · application/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
}

Errors

This endpoint can return these errors. Every code is described in the error catalog.