Документация по API Upload24

Конечные точки загрузки видео, аутентификация и поток запросов

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

Быстрый старт Аутентификация Конечные точки Примеры

Быстрый старт

Если вам нужен только кратчайший путь к рабочей интеграции, сначала выполните эти три шага, а затем используйте ссылку на конечную точку.

Шаг 1

Создайте ключ API на приборной панели

Ключи API генерируются через аутентифицированную на предъявителя сессию приборной панели. Возвращенный ключ будет показан только один раз, поэтому сохраняйте его сразу.

Шаг 2

Отправляйте X-Api-ключ при запросах на загрузку

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

Шаг 3

Выберите поток загрузки, соответствующий вашей инфраструктуре

Используйте multipart/form-data для кратчайшей интеграции, presign-put для прямой загрузки объектов или multipart presigning для больших файлов и возобновляемой передачи.

Модель аутентификации

Управление ключами защищено аутентификацией по предъявителю, в то время как при выгрузке принимается либо аутентификация по предъявителю, либо необработанный ключ 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-ключ или Bearer JWT
Запрос
multipart/form-data
POST /api/upload/presign-put

Создание сеанса одноразовой загрузки

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

Авторизация
X-Api-ключ или Bearer JWT
Запрос
application/json
POST /api/upload/multipart

Создание сеанса многокомпонентной загрузки

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

Авторизация
X-Api-ключ или Bearer JWT
Запрос
application/json
POST /api/upload/complete

Завершите сеанс загрузки

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

Авторизация
X-Api-ключ или Bearer JWT
Запрос
application/json
POST /api/upload/abort

Прервать сеанс загрузки

Отменяет незавершенный сеанс выгрузки и по возможности удаляет поставленный объект.

Авторизация
X-Api-ключ или Bearer JWT
Запрос
application/json
GET /api/upload/{uploadId}/status

Получение статуса загрузки

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

Авторизация
X-Api-ключ или Bearer JWT
Запрос
Нет тела
GET /uploads

Список загрузок арендаторов

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

Авторизация
Только носитель JWT
Запрос
Параметры запроса

Правила проверки и ограничения для моделирования в вашем клиенте

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

Значения общественного статуса

Scheduled

Запись о загрузке принята и ожидает запланированного окна отправки.

Processing

Загрузка активно отправляется или повторяется. Внутренние состояния Retrying и Dispatching представлены как 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 разделен на управление ключами, создание сессий загрузки и отслеживание доставки для каждого аккаунта.

Читать статью Открыть приборную панель