Upload24 API-документація

Кінцеві точки завантаження відео, автентифікація та потік запитів

На цій сторінці задокументовано практичний API для завантаження: як створити ключ, який заголовок надсилати, яку кінцеву точку викликати для кожної стратегії завантаження та які обмеження мають значення у виробництві.

Швидкий старт Аутентифікація Кінцеві точки Приклади

Швидкий старт

Якщо вам потрібен лише найкоротший шлях до робочої інтеграції, спочатку виконайте ці три кроки, а потім використовуйте посилання на кінцеву точку.

Крок 1

Створіть API-ключ в панелі керування

Ключі API генеруються під час сеансу роботи з інформаційною панеллю з автентифікацією пред'явника. Отриманий ключ відображається лише один раз, тому зберігайте його негайно.

Крок 2

Надсилайте X-Api-Key на запити на завантаження

Кінцеві точки створення, завершення, переривання та статусу завантаження приймають необроблений API-ключ у заголовку X-Api-Key. Не додавайте до нього префікс Bearer.

Крок 3

Виберіть потік завантаження, який відповідає вашій інфраструктурі

Використовуйте багатокомпонентні/форма-дані для найкоротшої інтеграції, preign-put для прямого завантаження об'єктів або багатокомпонентне попереднє підписання для великих файлів і повторного перенесення.

Модель автентифікації

Управління ключами захищено автентифікацією пред'явника, тоді як виконання завантаження приймає або автентифікацію пред'явника, або необроблений API-ключ. Специфічний для завантаження заголовок має назву X-Api-Key і повинен містити повний рядок ключа без префікса.

Оперативна записка: Запити на завантаження працюють лише тоді, коли цільові акаунти вже прив'язані до поточного орендаря. Ключі API не замінюють крок прив'язки акаунта в інформаційній панелі.

Створіть ключ

curl -X POST "$BASE_URL/api-keys/generate" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI uploads"
  }'

Використовуйте повернутий ключ у запитах на вивантаження

curl -X GET "$BASE_URL/api/upload/$UPLOAD_ID/status" \
  -H "X-Api-Key: $API_KEY"

Посилання на кінцеву точку

Це маршрути, які мають значення для наскрізної автоматизації завантаження. У таблиці вказано режим авторизації, тип корисного навантаження та завдання, яке виконує кожна кінцева точка.

POST /api-keys/generate

Згенеруйте ключ API

Створює новий ключ для поточного орендаря. Тіло запиту підтримує необов'язкове поле імені. Повний ключ повертається тільки у цій відповіді.

Авт.: JWT на пред'явника
Запит: application/json

POST /api/upload

Пряме завантаження форми

Завантажує метадані та двійковий файл одним запитом. Найкраще підходить для простих клієнтів і невеликих інтеграцій на стороні сервера.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: multipart/form-data

POST /api/upload/presign-put

Створіть сеанс однократного завантаження

Повертає токен сеансу, ідентифікатор файлу та пряму URL-адресу для завантаження. Після завантаження об'єкта завершіть потік за допомогою /api/upload/complete.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: application/json

POST /api/upload/multipart

Створіть сеанс завантаження з кількох частин

Повертає попередньо підписані URL-адреси для кожної частини разом з токеном сеансу. Використовуйте його, коли великі файли або нестабільна мережа роблять передачу частинами безпечнішою.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: application/json

POST /api/upload/complete

Завершити сеанс завантаження

Завершує потік з одним або кількома платежами і створює фактичний запис завантаження, який починає обробку на цільові рахунки.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: application/json

POST /api/upload/abort

Перервати сеанс завантаження

Скасовує незавершений сеанс завантаження і видаляє об'єкт, якщо це можливо.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: application/json

GET /api/upload/{uploadId}/status

Отримати статус завантаження

Повертає агрегований статус плюс деталі доставки для кожного акаунта, включаючи зовнішні ідентифікатори та інформацію про збої, якщо вони доступні.

Авт.: X-Api-ключ або JWT на пред'явника
Запит: Тіла немає.

GET /uploads

Список завантажень орендарів

Кінцева точка, орієнтована на дашборд, для посторінкової історії завантажень. Він не доступний через API key auth.

Авт.: Тільки на пред'явника JWT
Запит: Параметри запиту

Правила валідації та обмеження для моделі у вашому клієнті

Файли повинні мати розмір не більше 0 байт і не більше 2 ГБ.
Для кожного завантаження потрібен принаймні один пов'язаний обліковий запис, який належить поточному орендарю.
Поле заголовка є обов'язковим і не повинно перевищувати 2200 символів.
Заплановані посади не можуть бути створені більш ніж на один рік у майбутньому.
Квота нараховується на цільовий рахунок, а не на API-запит.
Коли ви додаєте метадані YouTube, обов'язковими стають categoryId, defaultLanguage та defaultAudioLanguage.

Значення публічного статусу

Scheduled

Запис завантаження прийнято і він чекає на своє заплановане вікно відправлення.

Processing

Завантаження активно відправляється або повторюється. Внутрішні стани "Повторна спроба" і "Відправлення" представлені як "Обробка".

Uploaded

Цільова платформа підтвердила публікацію для входу в обліковий запис.

Failed

Вивантаження не вдалося завершити принаймні для одного пункту призначення. Перевірте значення errorCode та errorMessage для кожного акаунта.

Приклади запитів

Використовуйте ці приклади як відправну точку. Замініть заповнювачі на вашу фактичну базову URL-адресу, токен пред'явника, ключ API, ідентифікатори облікових записів та шляхи до файлів.

Завантаження декількох частин одним запитом

curl -X POST "$BASE_URL/api/upload" \
  -H "X-Api-Key: $API_KEY" \
  -F "title=Spring launch teaser" \
  -F "accounts=account_123" \
  -F "accounts=account_456" \
  -F "scheduledOn=2026-04-18T09:30:00Z" \
  -F "file=@./video.mp4"

Заздалегідь визначений потік з одним входом

curl -X POST "$BASE_URL/api/upload/presign-put" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Spring launch teaser",
    "accounts": ["account_123"],
    "fileName": "video.mp4",
    "fileSize": 734003200,
    "contentType": "video/mp4"
  }'

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @./video.mp4

curl -X POST "$BASE_URL/api/upload/complete" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionToken": "$SESSION_TOKEN",
    "parts": []
  }'

Хочете ще й архітектурний огляд?

У першій статті блогу Upload24 пояснюється, чому API розділено на управління ключами, створення сесії завантаження та відстеження доставки для кожного акаунта.

Читати статтю Відкрийте приладову панель