Перейти к содержимому
RU
Ключ API
Обзор документации

Справочник API

API обработки Bulk

Создавайте и управляйте заданиями YouTube на основе файлов, а затем извлекайте их манифесты и части результатов.

На этой странице

Песочница API

Выберите источник и скопируйте полный рабочий процесс Python или Bash, один запрос или образец ответа. Код предварительного просмотра игровой площадки; он не предоставляет работу. Полные рабочие процессы обрабатывают загрузку, проверку статуса и поиск каждой части результата.

Параметры источника

Создайте рабочий процесс Bulk

Локальный файл UTF-8, один YouTube ID в строке, до 2 GiB. Требования к вводу.

Расширенные медиа-варианты

Медиа-центр

Blank использует дату загрузки UTC (YYYYMMDD).

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

Учетные данные поставщика и требования к хранению
Bulk Завершение web-cookУведомление о завершении манифеста и проверка
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

api_key = "YOUR_API_KEY"
api_url = "https://api.flashdata.dev/v2"
input_file = Path("video-ids.txt")
output_dir = Path("bulk-results")
bulk_id = ""  # Paste a saved Bulk ID to monitor/retrieve it without submitting again.
poll_timeout_seconds = 1800
payload = {
    "source": "youtube_download",
    "options": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "audio_language": "default",
        "upload_metadata": False,
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(NoRedirect())
os.umask(0o077)

def api(path, method="GET", body=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(5):
        try:
            request = urllib.request.Request(api_url + path, data=data, headers=headers, method=method)
            with opener.open(request, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            if method != "GET" or error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            retry_after = error.headers.get("Retry-After", "")
            delay = min(120, int(retry_after)) if retry_after.isdigit() else 2 ** attempt
            time.sleep(delay + random.random())

def result_location(path):
    request = urllib.request.Request(api_url + path, headers={"X-API-Key": api_key})
    try:
        with opener.open(request, timeout=60):
            raise RuntimeError("Expected a 302 result redirect")
    except urllib.error.HTTPError as error:
        if error.code != 302:
            raise
        location = error.headers.get("Location", "")
    parsed = urllib.parse.urlsplit(location)
    if parsed.scheme != urllib.parse.urlsplit(api_url).scheme or not parsed.hostname or parsed.username or parsed.password:
        raise RuntimeError("Invalid signed storage URL")
    return location

if not bulk_id:
    if not input_file.is_file() or not 1 <= input_file.stat().st_size <= 2147483648:
        raise ValueError("Use a nonempty UTF-8 ID file up to 2 GiB")
    created = api("/bulk-jobs", "POST", payload)
    bulk_id = created["job"]["id"]
    if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
        raise RuntimeError("Invalid Bulk ID")
    work = output_dir / bulk_id
    work.mkdir(parents=True, exist_ok=True)
    (work / "created.json").write_text(json.dumps(created, indent=2))
    print("Saved Bulk ID:", bulk_id, flush=True)
    upload = created["upload"]
    upload_url = urllib.parse.urlsplit(upload["href"])
    if upload["method"] != "PUT" or upload_url.scheme != urllib.parse.urlsplit(api_url).scheme or not upload_url.hostname or upload_url.username or upload_url.password:
        raise RuntimeError("Invalid signed upload URL")
    with input_file.open("rb") as file:
        request = urllib.request.Request(upload["href"], data=file, method="PUT", headers={
            "Content-Type": upload["contentType"], "Content-Length": str(input_file.stat().st_size)
        })
        with opener.open(request, timeout=120) as response:
            response.read()
    api("/bulk-jobs/" + bulk_id + "/start", "POST")

if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
    raise ValueError("Invalid Bulk ID")
work = output_dir / bulk_id
work.mkdir(parents=True, exist_ok=True)
deadline = time.monotonic() + poll_timeout_seconds
while True:
    job = api("/bulk-jobs/" + bulk_id)["job"]
    (work / "status.json").write_text(json.dumps(job, indent=2))
    print(job["status"], job["input"], job["counts"], flush=True)
    if job["status"] == "completed":
        break
    if job["status"] in ("paused", "failed", "cancelled", "awaiting_upload"):
        raise RuntimeError(json.dumps({"id": bulk_id, "status": job["status"], "pauseReason": job.get("pauseReason"), "error": job.get("error")}))
    if time.monotonic() >= deadline:
        raise TimeoutError("Job still running. Set bulk_id to " + bulk_id + " and rerun to continue monitoring.")
    time.sleep(10 + random.random())

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
Создавать, загружать, запускать, контролировать и извлекать все частиАутентификация X-API-Key

Конечные точки

Все конечные точки используют https://api.flashdata.dev/v2. Создайте задание → загрузите файл видео-ID → начните → просмотрите → извлеките манифест и каждую часть результата.

методПутьМеры
POST/v2/bulk-jobsСоздать работу Bulk
POST/v2/bulk-jobs/{bulkId}/startЗагрузить и начать
GET/v2/bulk-jobs/{bulkId}Статус работы
GET/v2/bulk-jobsСписок рабочих мест
POST/v2/bulk-jobs/{bulkId}/pauseПриостановить работу
PATCH/v2/bulk-jobs/{bulkId}Обновление вариантов работы
POST/v2/bulk-jobs/{bulkId}/resumeВозобновить работу
DELETE/v2/bulk-jobs/{bulkId}Отменить работу
GET/v2/bulk-jobs/{bulkId}/resultsПолучите манифест результата
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Скачать части результатов

Аутентификация и ввод

Установите FLASHDATA_API_KEY на ключ с доступом к выбранному источнику. Повторное использование одного и того же ключа и учетной записи для создания, контроля и результатов. Обработка использует баланс счета и нормальную цену на источник. YouTube Download требует доступа владельца и options.storage.

Создайте рабочую папку под названием bulk-api/ и запустите из нее эти примеры. Полный рабочий процесс Python на игровой площадке использует стандартную библиотеку Python 3.10 +; отдельные примеры конечных точек Python ниже требуют Запросов; примеры cURL используют Bash, cURL 7.76 +, jq и gzip. Выберите один язык для каждого действия, чтобы вы не создавали или не начинали дублировать работу.

Ввод - это файл UTF-8 с одним 11-символом YouTube ID в строке, вплоть до 2 GiB. Используйте IDs, а не URLs. Удалите дубликат IDs перед загрузкой; повторный IDs обрабатывается отдельно.

ИсточникОбщие варианты
youtube_metadatainclude_formats, include_chapters
youtube_transcriptЯзык, авто
youtube_captionsЯзык, авто
youtube_trainabilityНет вариантов
youtube_downloadВарианты медиа и место хранения
Python - зависимость
python -m pip install requests

Создать поля запросов

ПолеТиписпользование
sourcestringТребуется. Один поддерживаемый источник для каждого входа ID.
optionsobjectВарианты с общими источниками. Источники данных могут устанавливать result_storage; YouTube Download требует хранения.
callback_urlstringОпциональный публичный обратный вызов HTTPS. Отправлено после явной публикации.

Создать работу Bulk

Создайте задание, загрузите текстовый файл UTF-8 с одним 11-символом YouTube видео ID в строку на upload.href, затем вызовите старт. Создание работы само по себе не начинается с обработки.

Этот пример записывает video-ids.txt и сохраняет квитанцию 201 в bulk-created.json. Держите эту квитанцию в секрете и повторно используйте job.id для каждого последующего запроса. Создание работы оставляет ее в awaiting_upload; загрузка URL истекает через минуты 15.

Конечная точка
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Сохранить bulk_create.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

bulk_create.py
import json
import os
from pathlib import Path

import requests

os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
    "https://api.flashdata.dev/v2/bulk-jobs",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "youtube_metadata", "options": {"include_formats": False}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))
Бег от сыпучих апи/
python bulk_create.py

Схема ответов и запросов

HTTP статусЗначение
201Bulk Работа, созданная с помощью 15- минутная прямая загрузка URL
401Требуемая или недействительная аутентификация
422Проверка запроса не удалась
503Необходимая зависимость или каталог временно недоступны
Тело запроса
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Загрузить и начать

Начните обработку загруженного видео UTF-8 ID, вплоть до 2 GiB (байт 2147483648). Держите файл без изменений после запуска.

Первый PUT video-ids.txt к квитанции upload.href с upload.contentType, без X-API-Key. Примерные вызовы начинаются только после того, как загрузка удалась. После этого сохраняйте загруженный файл неизменным.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Сохранить bulk_start.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

bulk_start.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
    raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
    response = requests.put(
        upload["href"], data=file,
        headers={"Content-Type": upload["contentType"]},
        timeout=300, allow_redirects=False,
    )
    response.raise_for_status()
    if not 200 <= response.status_code < 300:
        raise RuntimeError("Upload did not complete; do not start the job yet")

bulk_id = receipt["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))
Бег от сыпучих апи/
python bulk_start.py

Ответы

HTTP статусЗначение
200Запуск Bulk или его нынешнее идемпотентное состояние
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
409Конфликт состояния ресурсов или идемпотентности
422Проверка запроса не удалась
503Необходимая зависимость или каталог временно недоступны
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Статус работы

Прочитайте job.status, вход, подсчет, pauseReason и ошибку. Перепроверьте тот же ID с задержкой; завершенный означает, что манифест опубликован, а не то, что каждое видео получилось.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Сохранить bulk_status.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

bulk_status.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
Бег от сыпучих апи/
python bulk_status.py

Ответы

HTTP статусЗначение
200Bulk - состояние работы
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Список рабочих мест

Ответ содержит данные и пагинацию. Перейдите pagination.nextCursor в качестве параметра запроса курсора следующего запроса, пока он не станет null. Используйте ограничение от 1 до 50; по умолчанию 20.

ПараметрМестоположениеТребование
cursorqueryНеобязательно · {"type":"string","maxLength":512}
limitqueryНеобязательно · {"type":"integer","minimum":1,"maximum":50,"default":20}
Конечная точка
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Сохранить list_bulk_jobs.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

list_bulk_jobs.py
import json
import os
from pathlib import Path

import requests

response = requests.get(
    "https://api.flashdata.dev/v2/bulk-jobs?limit=20",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Бег от сыпучих апи/
python list_bulk_jobs.py

Ответы

HTTP статусЗначение
200Рабочая страница Bulk
401Требуемая или недействительная аутентификация
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Приостановить работу

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

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Сохранить pause_bulk_job.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

pause_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Бег от сыпучих апи/
python pause_bulk_job.py

Ответы

HTTP статусЗначение
200Приостановленная работа или ее нынешнее идемпотентное состояние
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Обновление вариантов работы

Варианты обновления в ожидании загрузки или во время паузы до того, как весь ввод был прочитан. Существующие рабочие места сохраняют свои настройки. Если пауза все еще продолжается, подождите и повторите ответ 409. После того, как все входные данные были прочитаны, могут быть обновлены только учетные данные доставки. Установите callback_url на null, чтобы удалить его.

Этот пример устраняет обратный вызов завершения. Чтобы изменить параметры источника, вместо этого отправьте объект опций. Сначала приостановите и дождитесь, пока пауза вступит в силу; а 409 означает, что обновление еще не может быть применено. Существующие детские рабочие места сохраняют свои первоначальные возможности.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Сохранить update_bulk_job.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

update_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"callback_url": None},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Бег от сыпучих апи/
python update_bulk_job.py

Схема ответов и запросов

HTTP статусЗначение
200Обновленное состояние массового труда
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
409Конфликт состояния ресурсов или идемпотентности
422Проверка запроса не удалась
Тело запроса
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Возобновить работу

Сначала исправьте pauseReason, например, добавьте кредиты или обновите учетные данные хранилища, а затем возобновите тот же Bulk ID.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Сохранить resume_bulk_job.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

resume_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Бег от сыпучих апи/
python resume_bulk_job.py

Ответы

HTTP статусЗначение
200Текущее состояние массового труда
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Отменить работу

Остановите новые предложения. Существующие рабочие места могут по-прежнему иметь finish и нести свои обычные расходы. Отмененная работа не публикует окончательный манифест.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Сохранить cancel_bulk_job.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

cancel_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Бег от сыпучих апи/
python cancel_bulk_job.py

Ответы

HTTP статусЗначение
200Текущее состояние массового труда
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Получите манифест результата

Следуйте перенаправлению для загрузки манифеста JSON и используйте его ссылки для извлечения файлов результатов. Принесите подписанное хранилище URLs без ключа API. Результаты остаются доступными для 24 через несколько часов после завершения работы Bulk.

Аутентичный запрос API возвращает 302 с заголовком Location. Приведите HTTPS для хранения URL в отдельном запросе без X-API-Key. В качестве примера можно привести manifest.json. 409 означает, что результаты не готовы; 410 означает, что они истекли.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Конечная точка
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Сохранить bulk_manifest.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

bulk_manifest.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

manifest = requests.get(url, timeout=120)  # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))
Бег от сыпучих апи/
python bulk_manifest.py

Ответы

HTTP статусЗначение
200Манифест JSON скачан после перенаправления
302Перенаправить на недолговечный частный R2 URL; Учетные данные API не должны быть переадресованы · Location
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
409Конфликт состояния ресурсов или идемпотентности
410Сохранившийся результат истек
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Скачать части результатов

Используйте каждый parts[].number от manifest.json. Каждая конечная точка возвращает 302 в gzip-файл NDJSON; загружается без ключа API, декомпрессируется, а затем анализируется один объект JSON на строку. Присоединяйтесь к нулевому индексу. В примере извлекаются все части и хранятся файлы .ndjson.gz и .ndjson.

ПараметрМестоположениеТребование
bulkIdpathОбязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathОбязательно · {"type":"integer","minimum":0}
Конечная точка
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Сохранить bulk_parts.py в сыпучих апи / рядом с bulk-created.json. Скопируйте полный сценарий, а затем запустите команду ниже него.

bulk_parts.py
import json
import os
from pathlib import Path

import requests
import gzip
import shutil

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
    number = part["number"]
    response = requests.get(
        f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
        headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
        timeout=30, allow_redirects=False,
    )
    response.raise_for_status()
    if response.status_code != 302:
        raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
    url = response.headers["Location"]
    if not url.startswith("https://"):
        raise ValueError("Expected an HTTPS storage URL")

    # Save the original gzip bytes; do not decompress twice.
    with requests.get(url, stream=True, timeout=120) as download:
        download.raise_for_status()
        with open(f"part-{number}.ndjson.gz", "wb") as file:
            download.raw.decode_content = False
            shutil.copyfileobj(download.raw, file)
    with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
        with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
            for line in rows:
                file.write(line)
                print(json.dumps(json.loads(line)))
Бег от сыпучих апи/
python bulk_parts.py

Ответы

HTTP статусЗначение
200Gzip-сжатый NDJSON скачан после перенаправления
302Перенаправить на недолговечный частный R2 URL; Учетные данные API не должны быть переадресованы · Location
401Требуемая или недействительная аутентификация
404Ресурс не найден или не принадлежит абоненту
409Конфликт состояния ресурсов или идемпотентности
410Сохранившийся результат истек
200 · application/x-ndjson
{
  "type": "string"
}

Условия работы и удержание

Результаты остаются доступными для 24 через несколько часов после завершения работы Bulk. Сохраните их перед expiresAt. Средства массовой информации в вашем пункте назначения следуют политике удержания вашего ведра. Завершенная работа может включать в себя неудачные видео; записи counts.invalid отклоняются входными линиями.

государствоСледующее действие
awaiting_uploadЗагрузите файл и начните звонить.
runningОпросите тот же ID с обратным выключением; input.complete показывает, закончилось ли сканирование.
pausedПрочитайте pauseReason, исправьте, затем возобновите.
finalizingЖдите результатов упаковки и явной публикации.
completedЗагрузите манифест и все части. Проверьте статус и ошибку каждой строки.
failed / cancelledОцените ошибку и сохраненное состояние. Окончательный манифест не публикуется.

Доставка склада

Используйте игровую площадку для настройки провайдера и предварительного просмотра точных полей запросов. учетные данные клиента принадлежат выбранному объекту хранения; X-API-Key аутентифицирует только запросы FlashData API.

ИсточникСоздать поле запросаДоставка
Метаданные, транскрипт, подписи, проверка лицензииoptions.result_storageНеобязательно. Копии NDJSON приводят к частям и манифесту в ваше ведро.
youtube_downloadoptions.storageТребуется. Доставляет медиа в ваше ведро; result_storage и browser_delivery не принимаются.

Найдите доставленные файлы

Манифест данных написан последним и содержит списки ключей объектов, размеров и контрольных сумм SHA-256. Он отличается от манифеста FlashData, в котором перечислены значения href API. YYYYMMDD в каналах данных использует дату создания UTC Bulk; в каналах мультимедиа он использует дату загрузки UTC каждого видео. Для доставки данных Bulk OSS требуется конечная точка aliyuncs.com.

Значения file_url для частных носителей информации требуют вашего хранилища SDK или подписанного URL от этого поставщика. Ключ FlashData не предоставляет доступ к корзине. Факультативные файлы-компаньоны метаданных хранятся рядом со средствами массовой информации. Запросы доставки появляются в delivery.retryCount.

Планировка объекта данных
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Получить полную версию webhook

Поместите общедоступный HTTPS callback_url вне опций. Bulk отправляет заполненный только после публикации манифеста; он не отправляет никаких видео-мероприятий и никаких событий завершения для неудачных или отмененных рабочих мест. Сохраняйте статус-опрос как запасной вариант.

  1. Сохраняйте и размножайте delivery_id, а затем возвращайте 2xx быстро. Доставка повторяется до восьми раз с обратной связью.
  2. События не подписаны. Совместите идентификатор и источник с сохраненной квитанцией; проверьте, что завершено через аутентифицированное управление API, прежде чем искать в очереди. Игнорируйте URLs из непроверенного события.
Создать запрос с помощью callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Событие завершения · иллюстративное
{
  "delivery_id": "bulk-completion:bulk_EXAMPLE123",
  "id": "bulk_EXAMPLE123",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
      "method": "GET"
    }
  ]
}

Определения схемы

BulkJobCreated

BulkJobCreated
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job",
    "upload"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    },
    "upload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "href",
        "method",
        "expiresAt",
        "contentType"
      ],
      "properties": {
        "href": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "const": "PUT"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "contentType": {
          "type": "string",
          "const": "text/plain; charset=utf-8"
        }
      }
    }
  }
}

BulkJob

BulkJob
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "source",
    "status",
    "input",
    "counts",
    "delivery",
    "pauseReason",
    "error",
    "createdAt",
    "startedAt",
    "completedAt",
    "expiresAt",
    "links"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
    },
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_upload",
        "running",
        "paused",
        "finalizing",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bytes",
        "complete",
        "scannedBytes",
        "scannedLines"
      ],
      "properties": {
        "bytes": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        },
        "scannedBytes": {
          "type": "integer",
          "minimum": 0
        },
        "scannedLines": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "accepted",
        "completed",
        "failed",
        "invalid",
        "results"
      ],
      "properties": {
        "accepted": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "invalid": {
          "type": "integer",
          "minimum": 0
        },
        "results": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "pauseReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "customerStorage",
        "storageType",
        "uploadedParts",
        "retryCount"
      ],
      "properties": {
        "customerStorage": {
          "type": "boolean"
        },
        "storageType": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "s3",
            "s3_compatible",
            "oss",
            "gcs",
            "azure",
            "cos",
            "bos",
            "tos",
            null
          ]
        },
        "uploadedParts": {
          "type": "integer",
          "minimum": 0
        },
        "retryCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "error": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "detail"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "detail": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "startedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JobLink"
      }
    }
  }
}

BulkJobPage

BulkJobPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

BulkJobResponse

BulkJobResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    }
  }
}

CreateBulkJobRequest

CreateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "Optional public HTTPS endpoint notified once after manifest publication."
    }
  }
}

JobLink

JobLink
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "rel",
    "href",
    "method"
  ],
  "properties": {
    "rel": {
      "type": "string",
      "enum": [
        "self",
        "results",
        "content",
        "download"
      ]
    },
    "href": {
      "type": "string",
      "format": "uri"
    },
    "method": {
      "type": "string",
      "const": "GET"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 1
    }
  }
}

Pagination

Pagination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "hasMore",
    "limit"
  ],
  "properties": {
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "previousCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasMore": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Problem

Problem
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string",
      "pattern": "^req_"
    },
    "fieldErrors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FieldError"
      }
    }
  }
}

FieldError

FieldError
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

UpdateBulkJobRequest

UpdateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
    },
    "callback_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "maxLength": 2048,
      "description": "Replacement completion callback, or null to remove the callback."
    }
  }
}