Загрузка файлов через API

Kinescope предоставляет гибкие возможности для загрузки видео через API. Вы можете интегрировать медиафайлы напрямую в проекты и папки без промежуточных шагов. Этот метод позволяет контролировать доступ к ссылкам для загрузки файлов, а также скрывает API-токен Kinescope от пользователей клиентского приложения.

Кому подходит эта статья

• Разработчикам — нужно интегрировать загрузку видео в свои системы
• Администраторам платформ — требуется автоматизировать загрузку контента
• DevOps-инженерам — нужно настроить массовую загрузку видео

Когда вам нужна загрузка через API

Загрузка через API полезна, если:

• Нужна интеграция с вашей системой — автоматическая загрузка видео из вашего приложения
• Требуется контроль доступа — вы хотите управлять, кто может загружать файлы
• Безопасность — API-токен остаётся на сервере, а не в клиентском приложении
• Массовая загрузка — нужно загрузить много видео из CSV или другого источника

Способы загрузки

Kinescope поддерживает три способа загрузки:

1. Создание ссылки для загрузки — получите ссылку, которую можно использовать для загрузки (удобно для клиентских приложений)
2. Загрузка одним запросом — отправьте файл и метаданные в одном запросе
3. Загрузка по URL — укажите ссылку на видеофайл, Kinescope скачает его сам

Для больших файлов: Рекомендуем использовать протокол Tus для загрузки больших файлов частями. Пример реализации протокола здесь.

Подготовка: получение ID проекта или папки

Перед загрузкой видео нужно выбрать проект или папку для размещения файла. ID проекта или папки можно получить через API:

Перед началом работы: Если вы впервые используете Kinescope API, рекомендуем ознакомиться с общими правилами API — там описаны авторизация, формат токенов (UUID), пагинация и обработка ошибок.

Получение списка проектов:

curl --location 'https://api.kinescope.io/v1/projects' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}'

В ответе вы получите список проектов с их ID. Используйте id из ответа для получения списка папок в конкретном проекте.

Пагинация и сортировка: Списки проектов и папок поддерживают пагинацию (page, per_page) и сортировку (order). Подробнее в общих правилах API.

Получение списка папок в проекте:

curl --location 'https://api.kinescope.io/v1/projects/${PROJECT_ID}/folders' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}'

Замените ${PROJECT_ID} на ID проекта, полученный из предыдущего запроса.

В ответе вы получите список папок с их ID. ID проекта или папки можно использовать в параметре parent_id при загрузке видео.

Видео по настройке и работе с проектами:

Видео по настройке и работе с папками:

Способ 1: Создание ссылки для загрузки

Этот способ удобен, если нужно настроить загрузку напрямую через клиентское приложение. Вы получаете ссылку, которую можно передать клиенту для загрузки файла.

Пример запроса:

curl --location --request POST 'https://uploader.kinescope.io/v2/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--data-raw '{
    "filesize": 10485760,
    "type": "video",
    "title": "Моё видео",
    "parent_id": "e51e55a1-7615-493e-9055-10ac9cc44ccd",
    "filename": "video.mp4",
    "description": "Описание видео",
    "client_ip": "11.22.33.44"
}'

Ответ:

{
  "data": {
    "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
    "endpoint": "https://eu-ams-uploader-1.kinescope.io/v2/upload/0966958f-638b-4aab-bf4a-7f9860a57a93"
  }
}

Что дальше? Используйте endpoint из ответа для загрузки файла (см. раздел “Загрузка файла по полученной ссылке” ниже).

Параметры запроса

Общие параметры:

Параметры для типа video:

Параметры для типа attachment:

Загрузка файла по полученной ссылке

После получения ссылки (endpoint) загрузите файл через запрос POST. Эту же ссылку можно использовать для загрузки больших файлов частями через протокол Tus.

Пример запроса:

curl --location --request POST 'https://eu-ams-uploader-1.kinescope.io/v2/upload/0966958f-638b-4aab-bf4a-7f9860a57a93' \
--data-binary '@/path/to/video.mp4'

Способ 2: Загрузка видео одним запросом

В этом случае вся информация передаётся в заголовках запроса, а видеофайл — в его теле. Удобно для небольших файлов или когда нужно загрузить файл и сразу указать все метаданные.

Пример запроса:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Parent-ID: ${PARENT_ID}' \
--header 'X-Video-Title: ${TITLE}' \
--header 'X-Video-Description: ${DESCRIPTION}' \
--header 'Content-Type: video/mp4' \
--data-binary '@/path/to/video.mp4'

Заголовки запроса:

Способ 3: Загрузка видео по URL

Для загрузки можно использовать прямую ссылку на видеофайл или URL с YouTube (например, https://www.youtube.com/watch?v=UTgSnM3mA-4 или https://youtu.be/UTgSnM3mA-4). Kinescope сам скачает файл по указанной ссылке.

Пример запроса:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Parent-ID: ${PARENT_ID}' \
--header 'X-Video-Title: ${TITLE}' \
--header 'X-Video-URL: ${URL_TO_VIDEO_FILE}'

Заголовки запроса:

Прямые ссылки на постеры

После загрузки видео вы можете получить прямые ссылки на постеры (превью-изображения). Доступные размеры: xs, sm, md, lg.

Формат ссылок:

https://kinescope.io/{video_id}/poster.{jpg|webp}
https://kinescope.io/{video_id}/poster/{size}.{jpg|webp}

Примеры:

https://kinescope.io/2WFmbHsNz1W72DL9DGz2ps/poster.jpg
https://kinescope.io/2WFmbHsNz1W72DL9DGz2ps/poster/md.webp

Пример: массовый импорт из CSV

Если нужно загрузить много видео из CSV-файла, можно использовать простой bash-скрипт с curl. Это проще, чем писать полноценное приложение.

Важно: В CSV файле должны присутствовать колонки с названиями url и title.

Пример CSV файла:

url,title
https://example.com/video1.mp4,Название видео 1
https://example.com/video2.mp4,Название видео 2

Один запрос (пример)

Для загрузки одного видео по URL используйте такой curl-запрос:

curl --location --request POST 'https://uploader.kinescope.io/v2/video' \
--header 'Authorization: Bearer ${KINESCOPE_API_TOKEN}' \
--header 'X-Video-URL: https://example.com/video1.mp4' \
--header 'X-Video-Title: Название видео 1' \
--header 'X-Parent-ID: ${PARENT_ID}'

Bash-скрипт для массового импорта

Вот простой скрипт, который читает CSV и загружает все видео:

#!/bin/bash

# Настройки
KINESCOPE_API_TOKEN="ваш_api_токен"
PARENT_ID="id_проекта_или_папки"
CSV_FILE="videos.csv"

# Проверка наличия файла
if [ ! -f "$CSV_FILE" ]; then
    echo "Ошибка: файл $CSV_FILE не найден"
    exit 1
fi

# Пропускаем заголовок CSV (первую строку)
tail -n +2 "$CSV_FILE" | while IFS=',' read -r url title; do
    # Убираем пробелы и кавычки
    url=$(echo "$url" | tr -d ' "')
    title=$(echo "$title" | tr -d ' "')
    
    # Пропускаем пустые строки
    if [ -z "$url" ] || [ -z "$title" ]; then
        continue
    fi
    
    echo "Загрузка: $title ($url)"
    
    # Загрузка видео
    response=$(curl -s -w "\n%{http_code}" --location --request POST 'https://uploader.kinescope.io/v2/video' \
        --header "Authorization: Bearer $KINESCOPE_API_TOKEN" \
        --header "X-Video-URL: $url" \
        --header "X-Video-Title: $title" \
        --header "X-Parent-ID: $PARENT_ID")
    
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')
    
    if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
        video_id=$(echo "$body" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
        echo "  ✓ Успешно загружено. ID: $video_id"
    else
        echo "  ✗ Ошибка (HTTP $http_code): $body"
    fi
    
    echo ""
done

echo "Импорт завершён"

Как использовать:

1. Сохраните скрипт в файл (например, import.sh)
2. Сделайте его исполняемым: chmod +x import.sh
3. Укажите ваш API-токен и ID проекта/папки в переменных
4. Запустите: ./import.sh

Для разработчиков: Если нужна более сложная логика (обработка ошибок, параллельная загрузка, сохранение mapping), используйте Python, Node.js или другой язык. Но для простых случаев bash-скрипт с curl — самый быстрый вариант.

Какой способ выбрать?

• Создание ссылки для загрузки — если нужно дать клиенту возможность загружать файлы напрямую
• Загрузка одним запросом — для небольших файлов или когда нужно сразу указать все метаданные
• Загрузка по URL — если файлы уже находятся в интернете (YouTube, ваше хранилище и т.д.)

Всё! Теперь вы можете загружать видео через API Kinescope любым удобным способом.

Что дальше?

После настройки загрузки через API рекомендуем:

1. Пример реализации протокола Tus — загрузка больших файлов по частям
2. Общие правила API — авторизация и формат запросов
3. Kinescope API — полная документация API

Остались вопросы? Напишите в чат поддержки — специалисты помогут!