Saltar al contenido
ES
Obtener clave API
Explorar documentación

Referencia de la API

API de procesamiento Bulk

Crea y gestiona trabajos de YouTube a partir de archivos y recupera sus manifiestos y partes de resultados.

En esta página

Probador de la API

Elija una fuente y copiar un flujo completo de trabajo Python o Bash, una sola solicitud, o una respuesta de muestra. El código de vista preliminar del parque infantil; no presenta un trabajo. Los flujos de trabajo completos manejan la carga, los controles de estado y la recuperación de cada parte de resultado.

Parámetros de origen

Construir un flujo de trabajo Bulk

Local UTF-8, un YouTube ID por línea, hasta 2 GiB. Recursos necesarios.

Entrega de resultados

Deje esto para recuperar resultados a través de FlashData API.

Bulk webhook de terminaciónConfirmación y verificación de la terminación del Manifiesto
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_metadata",
    "options": {
        "include_formats": True,
        "include_chapters": True,
    },
}

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)
Crear, subir, iniciar, monitorear y recuperar todas las piezasautenticación X-API-Key

Puntos finales

Todos los puntos finales utilizan https://api.flashdata.dev/v2. Crear un trabajo → subir un archivo de video-ID → iniciar → monitor → recuperar el manifiesto y cada parte de resultado.

MétodoCaminoMedida
POST/v2/bulk-jobsCrear un trabajo Bulk
POST/v2/bulk-jobs/{bulkId}/startSubir y comenzar
GET/v2/bulk-jobs/{bulkId}Obtenga el estado de trabajo
GET/v2/bulk-jobsTrabajos de lista
POST/v2/bulk-jobs/{bulkId}/pausePausa un trabajo
PATCH/v2/bulk-jobs/{bulkId}Actualizar las opciones de trabajo
POST/v2/bulk-jobs/{bulkId}/resumeReanudar un trabajo
DELETE/v2/bulk-jobs/{bulkId}Cancelar un trabajo
GET/v2/bulk-jobs/{bulkId}/resultsObtenga el manifiesto del resultado
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Piezas de resultado de descarga

Autenticación e insumos

Establecer FLASHDATA_API_KEY a una clave con acceso a la fuente elegida. Reutilizar la misma clave y cuenta para la creación, los controles y los resultados. Procesar utiliza el equilibrio de la cuenta y los precios normales por fuente. YouTube Download requiere acceso al propietario y options.storage.

Cree una carpeta de trabajo llamada a granel/ y ejecute estos ejemplos de ella. Python flujo de trabajo utiliza el Python 3.10+ biblioteca estándar; el individuo Python a) Los ejemplos de puntos finales que figuran a continuación requieren solicitudes; cURL ejemplos de uso Bash, cURL 7.76+, jq y gzip. Elija un idioma para cada acción para que no cree o comience el trabajo duplicado.

La entrada es un archivo UTF-8 con un 11-character YouTube ID por línea, hasta 2 GiB. Use IDs, no URLs. Remove duplicate IDs antes de subir; repetido IDs se procesan por separado

FuenteOpciones compartidas
youtube_metadatainclude_formats, include_chapters
youtube_transcriptidioma, auto
youtube_captionsidioma, auto
youtube_trainabilityNo hay opciones
youtube_downloadOpciones de medios y destino de almacenamiento
Dependencia de Python
python -m pip install requests

Crear campos de solicitud

CampoTipoUso
sourcestringSe requiere. Una fuente compatible para cada entrada ID.
optionsobjectOpciones de fuente compartida. Fuentes de datos pueden establecer result_storage; YouTube Download requiere almacenamiento.
callback_urlstringLlamada de terminación pública HTTPS. Enviado después de la publicación manifiesta.

Crear un trabajo Bulk

Cree un trabajo, suba un archivo de texto UTF-8 con un 11-character YouTube de vídeo ID por línea a upload.href, luego llame al inicio. Crear el trabajo por sí solo no comienza el procesamiento.

Este ejemplo escribe video-ids.txt y guarda el recibo 201 a bulk-created.json. Mantenga que la recepción privada y reutiliza job.id para cada solicitud posterior. Crear un trabajo lo deja en awaiting_upload; la carga URL expira después de los minutos 15.

Punto final
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Guardar bulk_create.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python bulk_create.py

Respuestas y esquema de solicitud

Estado de HTTPSignificado
201Bulk creado con un 15-minuto de carga directa URL
401Autenticación requerida o inválida
422Solicitud de validación falló
503Una dependencia o un catálogo requerido no está disponible temporalmente
Solicitud de cuerpo
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Subir y comenzar

Comience a procesar el archivo UTF-8 subido ID, hasta 2 GiB (2147483648 bytes). Mantenga el archivo sin cambios después de comenzar.

Primero PUT video-ids.txt en el upload.href del recibo con upload.contentType, sin X-API-Key. El ejemplo llama a iniciar sólo después de cargar éxitos. Mantenga el archivo subido sin cambios después.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Guardar bulk_start.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python bulk_start.py

Respuestas

Estado de HTTPSignificado
200Bulk comenzó su trabajo o su estado actual de idempotente
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
409Conflicto de estado de recursos o idempotencia
422Solicitud de validación falló
503Una dependencia o un catálogo requerido no está disponible temporalmente
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Obtenga el estado de trabajo

Lea job.status, entrada, cuenta, pauseReason y error. Remarque el mismo ID con un retraso; complete significa que el manifiesto se publica, no que cada vídeo tuvo éxito.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Guardar bulk_status.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python bulk_status.py

Respuestas

Estado de HTTPSignificado
200Bulk estado de trabajo
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Trabajos de lista

La respuesta contiene datos y paginación. Pase pagination.nextCursor como parámetro de consulta de cursor de la siguiente solicitud hasta que esté nulo. Limite el uso desde 1 a 50; el valor predeterminado es 20.

ParámetroUbicaciónRequisitos
cursorqueryOpcional · {"type":"string","maxLength":512}
limitqueryOpcional · {"type":"integer","minimum":1,"maximum":50,"default":20}
Punto final
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Guardar list_bulk_jobs.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python list_bulk_jobs.py

Respuestas

Estado de HTTPSignificado
200Página de trabajo Bulk
401Autenticación requerida o inválida
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Pausa un trabajo

Pausa nuevas presentaciones y empaquetado de resultados. Los trabajos existentes continúan con su configuración original y sus cargos. Reanuda el trabajo cuando esté listo.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Guardar pause_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python pause_bulk_job.py

Respuestas

Estado de HTTPSignificado
200Trabajo a granel usado o su estado actual de idempotente
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Actualizar las opciones de trabajo

Actualizar opciones mientras espera la subida, o mientras se detuvo antes de que se lea toda la entrada. Los trabajos existentes mantienen su configuración. Si la pausa todavía está en progreso, espere y vuelva a entrar 409 respuesta. Después de leer todas las entradas, sólo se pueden actualizar las credenciales de entrega. callback_url para anularlo para quitarlo.

Este ejemplo elimina el callback de terminación. Para cambiar las opciones de fuente, envíe un objeto de opciones en su lugar. Pausa primero y esperar a que la pausa para entrar en vigor; un 409 significa que la actualización no se puede aplicar todavía.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Guardar update_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python update_bulk_job.py

Respuestas y esquema de solicitud

Estado de HTTPSignificado
200Estado de trabajo a granel actualizado
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
409Conflicto de estado de recursos o idempotencia
422Solicitud de validación falló
Solicitud de cuerpo
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Reanudar un trabajo

Arreglar pauseReason primero, como añadir créditos o actualizar las credenciales de almacenamiento, luego reanudar el mismo Bulk ID.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Guardar resume_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python resume_bulk_job.py

Respuestas

Estado de HTTPSignificado
200Estado actual de trabajo a granel
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Cancelar un trabajo

Detener nuevas presentaciones. Los trabajos existentes todavía pueden terminar e incurrir en sus cargos normales. Un trabajo cancelado no publica un manifiesto final.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Guardar cancel_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python cancel_bulk_job.py

Respuestas

Estado de HTTPSignificado
200Estado actual de trabajo a granel
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Obtenga el manifiesto del resultado

Siga la redireccion para descargar el manifiesto JSON y utilice sus enlaces para recuperar los archivos de resultados. Obtenga el almacenamiento firmado URLs sin su llave API. Los resultados permanecen disponibles para las horas 24 después de que todo el trabajo Bulk complete.

La solicitud autenticada API devuelve 302 con un encabezado de ubicación.Indique que HTTPS de almacenamiento URL en una solicitud separada sin X-API-Key. El ejemplo ahorra manifest.json. A 409 significa que los resultados no están listos; 410 significa que expiraron.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Guardar bulk_manifest.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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))
Huir de vracs-api/
python bulk_manifest.py

Respuestas

Estado de HTTPSignificado
200JSON manifiesto descargado después de seguir la redireccion
302Redirect to a short-lived private R2 URL; API letters must not be forwarded · Location
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
409Conflicto de estado de recursos o idempotencia
410El resultado retenido ha expirado
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Piezas de resultado de descarga

Use cada uno parts[].number desde manifest.json. Cada punto final devuelve un 302 a un gilipollas NDJSON archivo; descarga sin el API llave, descompresa, luego pare uno JSON objeto por línea. Únete al índice basado en cero. El ejemplo recupera todas las partes y mantiene ambas.ndjson.gz y archivos .ndjson.

ParámetroUbicaciónRequisitos
bulkIdpathObligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathObligatorio · {"type":"integer","minimum":0}
Punto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Guardar bulk_parts.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.

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)))
Huir de vracs-api/
python bulk_parts.py

Respuestas

Estado de HTTPSignificado
200Gzip-compressed NDJSON descargado después de seguir la redireccion
302Redirect to a short-lived private R2 URL; API letters must not be forwarded · Location
401Autenticación requerida o inválida
404Recursos no encontrados o no propiedad del callador
409Conflicto de estado de recursos o idempotencia
410El resultado retenido ha expirado
200 · application/x-ndjson
{
  "type": "string"
}

Estados del trabajo y conservación de resultados

Los resultados permanecen disponibles para las horas 24 después de que todo el trabajo Bulk termine. Guardarlos antes de expiresAt. Los medios en su destino siguen la política de retención de su cubo. Un trabajo completado puede incluir videos fallidos; los registros counts.invalid rechazaron las líneas de entrada.

EstadoSiguiente acción
awaiting_uploadCargue el archivo y llame al inicio.
runningVotar el mismo ID con backoff; input.complete muestra si el escaneo terminó.
pausedLea pauseReason, límpialo, luego reanuda.
finalizingEsperar el resultado empaquetado y publicación manifiesta.
completedDescargue el manifiesto y cada parte. Inspeccione el estado y el error de cada fila.
failed / cancelledInspeccione el error y estado salvado. No se publica ningún manifiesto final.

Entrega de almacenamiento

Utilice el patio de recreo para configurar un proveedor y previsualizar los campos de solicitud exactos. Las credenciales de almacenamiento del cliente pertenecen al objeto de almacenamiento elegido; X-API-Key autenticados sólo FlashData API solicitudes.

FuenteCrear campo de solicitudEntrega
Metadatos, transcripción, subtítulos, cheque de licenciaoptions.result_storageOpcional. Copias NDJSON de las partes de resultado y un manifiesto a su cubo.
youtube_downloadoptions.storageSe requiere. Entrega medios a su cubo; result_storage y browser_delivery no son aceptados.

Encontrar los archivos entregados

El manifiesto de datos está escrito último y lista las teclas de objetos, tamaños y SHA-256 compruebas, difiere de las FlashData manifiesta, que lista API valores de href. YYYYYMMDD en las rutas de datos utiliza la UTC Bulk fecha de creación; en los medios utiliza la fecha de carga UTC de cada vídeo. Bulk La entrega de datos de OSS requiere un aliyuncs.com endpoint.

Medios privados file_url los valores necesitan su almacenamiento SDK o un firmado URL de ese proveedor. FlashData llave no otorga acceso al cubo. Los archivos opcionales de metadatos de acompañamiento se almacenan al lado de los medios. delivery.retryCount.

Diseño de objetos de datos
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Recibir un Webhook de terminación

Coloque un HTTPS callback_url fuera de las opciones. Bulk envía completado sólo después de la publicación del manifiesto; no envía eventos por vídeo y no evento de terminación para trabajos fallidos o cancelados. Mantenga la encuesta de estado como un retroceso.

  1. Persista y deduplicado delivery_id, a continuación, devuelve 2xx con prontitud. Retrección de entrega hasta ocho veces con respaldo.
  2. Los eventos no se firman. Match id y fuente a su recibo guardado; verifique completado a través de la gestión autenticada API antes de que el retroceso. Ignore URLs de un evento no verificado.
Crear solicitud con un callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Evento de finalización · ilustrativo
{
  "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"
    }
  ]
}

Definiciones de esquemas

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."
    }
  }
}