PRODUCTION REST API · v1

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

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

YTSaveClientJSON через HTTPSАсинхронные заданияОграниченные учетные данные

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

YTSave обрабатывает API-хост, сначала идентифицируя активированные поддержкой учётные данные. Затем следует назначенный конечный пункт арендатора и сохраняется путь вызова только для сервера.

URL арендатораhttps://ytsave.app

АутентификацияX-API-Key: ys_live_…

Профиль клиентаYTSaveClient

Версия APIv1

# Available only after support activation
export YTSAVE_API_KEY="issued-after-review"

curl -X POST https://ytsave.app/v1/resolve \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

Для объяснения безопасности учетных данных YTSave разделяет серверное хранение секретов и отсутствие встраивания в клиентский пакет. Запись доказательств не предоставляет публичных журналов или репозиториев собственного места.

Разрешить ссылку

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

ОТПРАВИТЬ/v1/resolveОбласть: разрешить

Поле	Тип	Обязательно	Описание
`url`	HTTPS URL	Да	Публичная или авторизованная страница СМИ для анализа.
`tenant`	строка	Нет	Назначенный домен арендатора. Обычно опускается.

{
  "success": true,
  "platform": "youtube",
  "title": "Example video",
  "formats": [
    {"id":"18","type":"video","quality":"360p","container":"mp4"}
  ],
  "cached": false
}

Чтобы объяснить идентификатор формата, YTSave отделяет возвращаемое значение без изменений от доступности по ссылке. Запись доказательства не присваивает предполагаемой метке качества отдельного места.

Создавать и отслеживать задание на загрузку

Для создания задания YTSave начинает с асинхронной подготовки. Его запись доказательств сочетает это с коротким HTTP-запросом и заканчивается ограниченным выполнением рабочего процесса.

ОТПРАВИТЬ/v1/jobsОбласть: вакансии

Поле	Тип	Обязательно	Описание
`url`	HTTPS URL	Да	Тот же нормализованный источник отправлен для разрешения.
`format_id`	строка	Да	Точный ID из ответа resolve.
`tenant`	строка	Нет	Назначенный домен арендатора. Обычно опускается.

curl -X POST https://ytsave.app/v1/jobs \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format_id":"18"}'

1202 ПринятоСохранить job_id.

2Статус опросаGET /v1/jobs/{job_id} с тем же ключом.

3ГотовоОткрыть подписанный URL для загрузки.

Статус	Значение	Действие клиента
`queued`	Принято в ограниченную очередь.	Повторить опрос с задержкой.
`extracting`	Обновление метаданных источника или маршрута.	Продолжить опрос.
`processing`	Загрузка, ремультиплексирование или объединение.	Отобразить прогресс сервера.
`ready`	Подписанная загрузка доступна.	Отправьте URL пользователю.
`failed`	Терминальная структурированная ошибка.	Читать `error_code`. Повторять попытку только по рекомендации.
`expired`	Временный вывод был удалён.	Создать новую задачу.

curl https://ytsave.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

YTSave облегчает опрос задач. Страница начинается с начального ожидания в одну секунду, переходит к ограниченному экспоненциальному увеличению интервала и чётко указывает временную подписанную доставку.

Предсказуемые ошибки

Для контракта ошибки YTSave проверяет один конверт с кодом, не начинающимся на 2xx, перед идентификатором запроса поддержки. Эта запись доказательств также делает понятной предсказуемую обработку на стороне клиента.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "category": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "retryable": true,
    "details": {"retry_after_seconds": 20}
  },
  "request_id": "…"
}

HTTP	Типичное значение	Действие
400	Недопустимый URL, тело или недоступный формат.	Исправьте запрос. Повторите разрешение для форматов.
401	Отсутствующий, недействительный, просроченный или с неправильными правами ключ.	Проверьте учетные данные на стороне сервера.
403	Арендатор или исходная политика отклонили запрос.	Не обходите политику. Свяжитесь с поддержкой.
404	Неизвестная или просроченная задача.	Создайте новую задачу, если это уместно.
429	Достигнут лимит запросов или активных заданий.	Честь `retry_after_seconds`.
503	Очередь/вместимость или источник временно недоступны.	Повторить с экспоненциальной задержкой и джиттером.

Операционный контракт

YTSave выдаёт операционную квоту с каждым подтверждением, чтобы защитить потребителя API и вышестоящие медиа-сервисы.

Используйте идемпотентную логику приложения и никогда не запускайте дублирующие задания для одного и того же клика пользователя.
Кэшируйте метаданные разрешения кратко, но всегда рассматривайте подписанные URL-адреса загрузки как истекающие.
Использовать ограниченный экспоненциальный откат с джиттером для 429, 503 и ошибки, которые можно повторить.
Обрабатывайте только публичные медиа или медиа, к которым у вас есть разрешение на доступ. DRM и средства контроля доступа не обходятся.
Сохраняйте идентификаторы запросов и идентификаторы заданий в приватных операционных журналах. Не записывайте отправленные URL без необходимости.

YTSave обрабатывает доступ к Схеме, сначала определяя активацию перед исследованием. Затем следует назначенная аутентификация и сохранение в поле зрения задокументированных форм запросов. Справочник OpenAPI

ДОСТУП, ПРОВЕРЕННЫЙ ОПЕРАТОРОМ

Запросить ваш API-ключ

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

Запросить доступ к API Ключи ограничены арендатором, могут быть отозваны и выдаются через форму контакта. Анонимные скрипты не могут выполнять работу загрузчика.