ПРАДПРЫЕМСТВА 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 і не захоўвае выдуманыя вынікі ў праглядзе.

POST/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-запытам і заканчваецца абмежаваным выкананнем работніка.

POST/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 Ключы маюць абмежаванне па арандатары, могуць быць адкліканы і выдаюцца праз форму кантакту. Ананімныя скрыпты не могуць выконваць працу загрузчыка.