Обзор документации
Справочник API
Создавайте и управляйте заданиями YouTube на основе файлов, а затем извлекайте их манифесты и части результатов.
На этой странице
Песочница API
Выберите источник и скопируйте полный рабочий процесс Python или Bash, один запрос или образец ответа. Код предварительного просмотра игровой площадки; он не предоставляет работу. Полные рабочие процессы обрабатывают загрузку, проверку статуса и поиск каждой части результата.
Создайте рабочий процесс Bulk
Локальный файл UTF-8, один YouTube ID в строке, до 2 GiB. Требования к вводу.
Расширенные медиа-варианты
Медиа-центр
Blank использует дату загрузки UTC (YYYYMMDD).
Добавьте свои учетные данные на сервер перед запуском кода. Им нужно разрешение для загрузки файлов.
Учетные данные поставщика и требования к хранениюBulk Завершение web-cook
Уведомление о завершении манифеста и проверкаhttps://api.flashdata.dev/v2/bulk-jobsКонечные точки
Все конечные точки используют 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_metadata | include_formats, include_chapters |
| youtube_transcript | Язык, авто |
| youtube_captions | Язык, авто |
| youtube_trainability | Нет вариантов |
| youtube_download | Варианты медиа и место хранения |
python -m pip install requestsСоздать поля запросов
| Поле | Тип | использование |
|---|---|---|
| source | string | Требуется. Один поддерживаемый источник для каждого входа ID. |
| options | object | Варианты с общими источниками. Источники данных могут устанавливать result_storage; YouTube Download требует хранения. |
| callback_url | string | Опциональный публичный обратный вызов 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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyumask 077
printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
curl --fail-with-body --silent --show-error \
'https://api.flashdata.dev/v2/bulk-jobs' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"youtube_metadata","options":{"include_formats":false}}' \
--output bulk-created.json &&
jq '.job | {id, source, status}' bulk-created.jsonСхема ответов и запросов
| HTTP статус | Значение |
|---|---|
| 201 | Bulk Работа, созданная с помощью 15- минутная прямая загрузка URL |
| 401 | Требуемая или недействительная аутентификация |
| 422 | Проверка запроса не удалась |
| 503 | Необходимая зависимость или каталог временно недоступны |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$ref": "#/components/schemas/BulkJobCreated"
}Загрузить и начать
Начните обработку загруженного видео UTF-8 ID, вплоть до 2 GiB (байт 2147483648). Держите файл без изменений после запуска.
Первый PUT video-ids.txt к квитанции upload.href с upload.contentType, без X-API-Key. Примерные вызовы начинаются только после того, как загрузка удалась. После этого сохраняйте загруженный файл неизменным.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
UPLOAD_URL=$(jq -er '.upload.href' bulk-created.json)
CONTENT_TYPE=$(jq -er '.upload.contentType' bulk-created.json)
curl --fail-with-body --silent --show-error --proto '=https' \
--header "Content-Type: $CONTENT_TYPE" \
--upload-file video-ids.txt "$UPLOAD_URL" &&
curl --fail-with-body --silent --show-error --request POST \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/start" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}"Ответы
| HTTP статус | Значение |
|---|---|
| 200 | Запуск Bulk или его нынешнее идемпотентное состояние |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
| 409 | Конфликт состояния ресурсов или идемпотентности |
| 422 | Проверка запроса не удалась |
| 503 | Необходимая зависимость или каталог временно недоступны |
{
"$ref": "#/components/schemas/BulkJobResponse"
}Статус работы
Прочитайте job.status, вход, подсчет, pauseReason и ошибку. Перепроверьте тот же ID с задержкой; завершенный означает, что манифест опубликован, а не то, что каждое видео получилось.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output bulk-job.json &&
jq '.job | {id, status, counts, pauseReason, error, expiresAt}' bulk-job.jsonОтветы
| HTTP статус | Значение |
|---|---|
| 200 | Bulk - состояние работы |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
{
"$ref": "#/components/schemas/BulkJobResponse"
}Список рабочих мест
Ответ содержит данные и пагинацию. Перейдите pagination.nextCursor в качестве параметра запроса курсора следующего запроса, пока он не станет null. Используйте ограничение от 1 до 50; по умолчанию 20.
| Параметр | Местоположение | Требование |
|---|---|---|
| cursor | query | Необязательно · {"type":"string","maxLength":512} |
| limit | query | Необязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pycurl --fail-with-body --silent --show-error --max-time 30 \
--request GET \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs?limit=20"Ответы
| HTTP статус | Значение |
|---|---|
| 200 | Рабочая страница Bulk |
| 401 | Требуемая или недействительная аутентификация |
{
"$ref": "#/components/schemas/BulkJobPage"
}Приостановить работу
Приостановите новые представления и упаковку результатов. Существующие рабочие места продолжаются с их первоначальными настройками и сборами. Возобновляйте работу, когда будете готовы.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/pause"Ответы
| HTTP статус | Значение |
|---|---|
| 200 | Приостановленная работа или ее нынешнее идемпотентное состояние |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
{
"$ref": "#/components/schemas/BulkJobResponse"
}Обновление вариантов работы
Варианты обновления в ожидании загрузки или во время паузы до того, как весь ввод был прочитан. Существующие рабочие места сохраняют свои настройки. Если пауза все еще продолжается, подождите и повторите ответ 409. После того, как все входные данные были прочитаны, могут быть обновлены только учетные данные доставки. Установите callback_url на null, чтобы удалить его.
Этот пример устраняет обратный вызов завершения. Чтобы изменить параметры источника, вместо этого отправьте объект опций. Сначала приостановите и дождитесь, пока пауза вступит в силу; а 409 означает, что обновление еще не может быть применено. Существующие детские рабочие места сохраняют свои первоначальные возможности.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request PATCH \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' --data '{"callback_url":null}' \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Схема ответов и запросов
| HTTP статус | Значение |
|---|---|
| 200 | Обновленное состояние массового труда |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
| 409 | Конфликт состояния ресурсов или идемпотентности |
| 422 | Проверка запроса не удалась |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$ref": "#/components/schemas/BulkJobResponse"
}Возобновить работу
Сначала исправьте pauseReason, например, добавьте кредиты или обновите учетные данные хранилища, а затем возобновите тот же Bulk ID.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/resume"Ответы
| HTTP статус | Значение |
|---|---|
| 200 | Текущее состояние массового труда |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
{
"$ref": "#/components/schemas/BulkJobResponse"
}Отменить работу
Остановите новые предложения. Существующие рабочие места могут по-прежнему иметь finish и нести свои обычные расходы. Отмененная работа не публикует окончательный манифест.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request DELETE \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Ответы
| HTTP статус | Значение |
|---|---|
| 200 | Текущее состояние массового труда |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
{
"$ref": "#/components/schemas/BulkJobResponse"
}Получите манифест результата
Следуйте перенаправлению для загрузки манифеста JSON и используйте его ссылки для извлечения файлов результатов. Принесите подписанное хранилище URLs без ключа API. Результаты остаются доступными для 24 через несколько часов после завершения работы Bulk.
Аутентичный запрос API возвращает 302 с заголовком Location. Приведите HTTPS для хранения URL в отдельном запросе без X-API-Key. В качестве примера можно привести manifest.json. 409 означает, что результаты не готовы; 410 означает, что они истекли.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.jsonОтветы
| HTTP статус | Значение |
|---|---|
| 200 | Манифест JSON скачан после перенаправления |
| 302 | Перенаправить на недолговечный частный R2 URL; Учетные данные API не должны быть переадресованы · Location |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
| 409 | Конфликт состояния ресурсов или идемпотентности |
| 410 | Сохранившийся результат истек |
{
"type": "object",
"additionalProperties": true
}Скачать части результатов
Используйте каждый parts[].number от manifest.json. Каждая конечная точка возвращает 302 в gzip-файл NDJSON; загружается без ключа API, декомпрессируется, а затем анализируется один объект JSON на строку. Присоединяйтесь к нулевому индексу. В примере извлекаются все части и хранятся файлы .ndjson.gz и .ndjson.
| Параметр | Местоположение | Требование |
|---|---|---|
| bulkId | path | Обязательно · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Обязательно · {"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. Скопируйте полный сценарий, а затем запустите команду ниже него.
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.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.json
# Run in the same Bash session as fetch_bulk_result.
jq -r '.parts[].number' manifest.json | while IFS= read -r PART; do
fetch_bulk_result "/$PART" "part-$PART.ndjson.gz" || exit
gzip -dc "part-$PART.ndjson.gz" > "part-$PART.ndjson" || exit
jq -c '{index, video_id, status, results, error}' "part-$PART.ndjson"
doneОтветы
| HTTP статус | Значение |
|---|---|
| 200 | Gzip-сжатый NDJSON скачан после перенаправления |
| 302 | Перенаправить на недолговечный частный R2 URL; Учетные данные API не должны быть переадресованы · Location |
| 401 | Требуемая или недействительная аутентификация |
| 404 | Ресурс не найден или не принадлежит абоненту |
| 409 | Конфликт состояния ресурсов или идемпотентности |
| 410 | Сохранившийся результат истек |
{
"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_download | options.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 отправляет заполненный только после публикации манифеста; он не отправляет никаких видео-мероприятий и никаких событий завершения для неудачных или отмененных рабочих мест. Сохраняйте статус-опрос как запасной вариант.
- Сохраняйте и размножайте delivery_id, а затем возвращайте 2xx быстро. Доставка повторяется до восьми раз с обратной связью.
- События не подписаны. Совместите идентификатор и источник с сохраненной квитанцией; проверьте, что завершено через аутентифицированное управление API, прежде чем искать в очереди. Игнорируйте URLs из непроверенного события.
{
"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
{
"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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BulkJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BulkJobResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
}
}
}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
{
"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
{
"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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}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."
}
}
}