Explorar documentación
Referencia de la API
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.
Construir un flujo de trabajo Bulk
Local UTF-8, un YouTube ID por línea, hasta 2 GiB. Recursos necesarios.
Deje en blanco para probar en-orig, luego en, y devuelva una pista. O introduzca un código o hasta 10 códigos distintos separados separados por comas.
Entrega de resultados
Deje esto para recuperar resultados a través de FlashData API.
Bulk webhook de terminación
Confirmación y verificación de la terminación del Manifiestohttps://api.flashdata.dev/v2/bulk-jobsPuntos 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étodo | Camino | Medida |
|---|---|---|
| POST | /v2/bulk-jobs | Crear un trabajo Bulk |
| POST | /v2/bulk-jobs/{bulkId}/start | Subir y comenzar |
| GET | /v2/bulk-jobs/{bulkId} | Obtenga el estado de trabajo |
| GET | /v2/bulk-jobs | Trabajos de lista |
| POST | /v2/bulk-jobs/{bulkId}/pause | Pausa un trabajo |
| PATCH | /v2/bulk-jobs/{bulkId} | Actualizar las opciones de trabajo |
| POST | /v2/bulk-jobs/{bulkId}/resume | Reanudar un trabajo |
| DELETE | /v2/bulk-jobs/{bulkId} | Cancelar un trabajo |
| GET | /v2/bulk-jobs/{bulkId}/results | Obtenga 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
| Fuente | Opciones compartidas |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | idioma, auto |
| youtube_captions | idioma, auto |
| youtube_trainability | No hay opciones |
| youtube_download | Opciones de medios y destino de almacenamiento |
python -m pip install requestsCrear campos de solicitud
| Campo | Tipo | Uso |
|---|---|---|
| source | string | Se requiere. Una fuente compatible para cada entrada ID. |
| options | object | Opciones de fuente compartida. Fuentes de datos pueden establecer result_storage; YouTube Download requiere almacenamiento. |
| callback_url | string | Llamada 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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYGuardar bulk_create.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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.jsonRespuestas y esquema de solicitud
| Estado de HTTP | Significado |
|---|---|
| 201 | Bulk creado con un 15-minuto de carga directa URL |
| 401 | Autenticación requerida o inválida |
| 422 | Solicitud de validación falló |
| 503 | Una dependencia o un catálogo requerido no está disponible temporalmente |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYGuardar bulk_start.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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}"Respuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Bulk comenzó su trabajo o su estado actual de idempotente |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
| 409 | Conflicto de estado de recursos o idempotencia |
| 422 | Solicitud de validación falló |
| 503 | Una dependencia o un catálogo requerido no está disponible temporalmente |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYGuardar bulk_status.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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.jsonRespuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Bulk estado de trabajo |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| cursor | query | Opcional · {"type":"string","maxLength":512} |
| limit | query | Opcional · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYGuardar list_bulk_jobs.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"Respuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Página de trabajo Bulk |
| 401 | Autenticación requerida o inválida |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYGuardar pause_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"Respuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Trabajo a granel usado o su estado actual de idempotente |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYGuardar update_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"Respuestas y esquema de solicitud
| Estado de HTTP | Significado |
|---|---|
| 200 | Estado de trabajo a granel actualizado |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
| 409 | Conflicto de estado de recursos o idempotencia |
| 422 | Solicitud de validación falló |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYGuardar resume_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"Respuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Estado actual de trabajo a granel |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYGuardar cancel_bulk_job.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"Respuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Estado actual de trabajo a granel |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
{
"$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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYGuardar bulk_manifest.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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.jsonRespuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | JSON manifiesto descargado después de seguir la redireccion |
| 302 | Redirect to a short-lived private R2 URL; API letters must not be forwarded · Location |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
| 409 | Conflicto de estado de recursos o idempotencia |
| 410 | El resultado retenido ha expirado |
{
"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ámetro | Ubicación | Requisitos |
|---|---|---|
| bulkId | path | Obligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Obligatorio · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYGuardar bulk_parts.py en vracs-api/ al lado de bulk-created.json. Copiar el script completo, luego ejecutar el comando debajo de él.
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"
doneRespuestas
| Estado de HTTP | Significado |
|---|---|
| 200 | Gzip-compressed NDJSON descargado después de seguir la redireccion |
| 302 | Redirect to a short-lived private R2 URL; API letters must not be forwarded · Location |
| 401 | Autenticación requerida o inválida |
| 404 | Recursos no encontrados o no propiedad del callador |
| 409 | Conflicto de estado de recursos o idempotencia |
| 410 | El resultado retenido ha expirado |
{
"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.
| Estado | Siguiente acción |
|---|---|
| awaiting_upload | Cargue el archivo y llame al inicio. |
| running | Votar el mismo ID con backoff; input.complete muestra si el escaneo terminó. |
| paused | Lea pauseReason, límpialo, luego reanuda. |
| finalizing | Esperar el resultado empaquetado y publicación manifiesta. |
| completed | Descargue el manifiesto y cada parte. Inspeccione el estado y el error de cada fila. |
| failed / cancelled | Inspeccione 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.
| Fuente | Crear campo de solicitud | Entrega |
|---|---|---|
| Metadatos, transcripción, subtítulos, cheque de licencia | options.result_storage | Opcional. Copias NDJSON de las partes de resultado y un manifiesto a su cubo. |
| youtube_download | options.storage | Se 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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonRecibir 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.
- Persista y deduplicado delivery_id, a continuación, devuelve 2xx con prontitud. Retrección de entrega hasta ocho veces con respaldo.
- 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.
{
"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"
}
]
}Definiciones de esquemas
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."
}
}
}