Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Referência da API

API de processamento Bulk

Criar e controlar trabalhos YouTube baseados em arquivos, e então recuperar seus manifestos e partes de resultados.

Nesta página

Playground da API

Escolha uma fonte e copie um Python completo ou Bash fluxo de trabalho, um único pedido, ou uma resposta de amostra. O parquinho pré-visualiza o código, ele não envia um trabalho. Fluxos de trabalho completos lidam com upload, verificação de status e recuperação de cada parte do resultado.

Parâmetros de origem

Construir um fluxo de trabalho Bulk

Arquivo UTF-8 local, um YouTube ID por linha, até 2 GiB. Requisitos de entrada.

Opções avançadas da mídia

Destino da mídia

Em branco usa a data de upload da mídia UTC (YYYMMDD).

Adicione suas credenciais de armazenamento no servidor antes de executar o código. Eles precisam de permissão para carregar arquivos.

Credenciais do fornecedor e requisitos de armazenamento
Bulk completando webhookNotificação e verificação de completamento do manifesto
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

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

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

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

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

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

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

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

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
Criar, carregar, iniciar, monitorar e recuperar todas as partesX-API-Key autenticação

Ponto final

Todos os terminais usam https://api.flashdata.dev/v2.. Criar um trabalho → carregar um arquivo de vídeo-ID → iniciar → monitor → recuperar o manifesto e cada parte do resultado.

MétodoCaminhoAção
POST/v2/bulk-jobsCriar um trabalho Bulk
POST/v2/bulk-jobs/{bulkId}/startCarregue e comece
GET/v2/bulk-jobs/{bulkId}Obter status de trabalho
GET/v2/bulk-jobsLista de trabalhos
POST/v2/bulk-jobs/{bulkId}/pausePause um trabalho
PATCH/v2/bulk-jobs/{bulkId}Atualizar opções de trabalho
POST/v2/bulk-jobs/{bulkId}/resumeRetomar um trabalho
DELETE/v2/bulk-jobs/{bulkId}Cancele um trabalho
GET/v2/bulk-jobs/{bulkId}/resultsPegue o manifesto do resultado
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Descarregue as peças dos resultados

Autenticação e entrada

Coloque FLASHDATA_API_KEY em uma chave com acesso à fonte escolhida. Reutilize a mesma chave e conte com criação, controles e resultados. Processar usa o saldo da conta e o preço normal por fonte. YouTube Download requer acesso do proprietário e options.storage.

Crie uma pasta de trabalho chamada Bulk-api e execute estes exemplos dela. O fluxo de trabalho Python completo do playground usa a biblioteca padrão Python 3.10+; os exemplos individuais do Python abaixo requerem Solicitações; exemplos cURL usam Bash, cURL 7.76+, jq e gzip. Escolha um idioma para cada ação para que você não crie ou comece a trabalhar em duplicata.

Input é um arquivo UTF-8 com um 11-caracter YouTube ID por linha, até 2 GiB. Use IDs, não URLs. Remova IDs duplicado antes de carregar, IDs repetido são processados separadamente.

FonteOpções compartilhadas
youtube_metadatainclude_formats include_chapters
youtube_transcriptLinguagem, auto
youtube_captionsLinguagem, auto
youtube_trainabilitySem opções
youtube_downloadOpções de mídia e destino de armazenamento
Python dependência
python -m pip install requests

Criar campos de solicitação

CampoTipoUso
sourcestringNecessário. Uma fonte suportada para cada entrada ID.
optionsobjectOpções de fonte compartilhada. Fontes de dados podem definir result_storage; YouTube Download requer armazenamento.
callback_urlstringChamada de conclusão pública opcional do HTTPS Enviado após a publicação do manifesto.

Criar um trabalho Bulk

Criar um trabalho, carregar um arquivo de texto UTF-8 com um 11-caractere YouTube vídeo ID por linha para upload.href, em seguida, ligar para iniciar. Criar o trabalho sozinho não começa a processar.

Este exemplo escreve video-ids.txt e salva o recibo 201 para bulk-created.json. Mantenha o recibo privado e reutilize job.id para cada pedido posterior. Criar um trabalho deixa-o em awaiting_upload; o upload URL expira após 15 minutos.

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

Salve bulk_create.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas e pedido de esquema

HTTP statusO que quer dizer?
201Bulk trabalho criado com um 15-minuto de upload direto URL
401Autenticação necessária ou inválida
422A validação do pedido falhou
503Uma dependência necessária ou catálogo está temporariamente indisponível
Corpo da requisição
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Carregue e comece

Comece a processar o UTF carregado.8 Vídeo ID Arquivo, até 2 GiB (2147483648 bytes). Mantenha o arquivo inalterado depois de começar.

Primeiro PUT video-ids.txt para o recibo upload.href com upload.contentType, sem X-API-Key. As chamadas de exemplo só começam depois que o upload é bem sucedido. Mantenha o arquivo carregado inalterado depois.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Salve bulk_start.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200Bulk começou ou seu estado atual idempotente
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
409Estado de recursos ou conflito de indemnidade
422A validação do pedido falhou
503Uma dependência necessária ou catálogo está temporariamente indisponível
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Obter status de trabalho

Leia job.status, entrada, conta, pauseReason e erro. Reverifique o mesmo ID com um atraso; completo significa que o manifesto é publicado, não que todo vídeo tenha sucesso.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salve bulk_status.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200Bulk trabalho estado
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Lista de trabalhos

A resposta contém dados e paginação. Passe pagination.nextCursor como parâmetro de consulta de cursores da próxima solicitação até que seja null. Use limite de 1 para 50; o padrão é 20.

ParâmetroLocalizaçãoRequisição
cursorqueryOpcional · {"type":"string","maxLength":512}
limitqueryOpcional · {"type":"integer","minimum":1,"maximum":50,"default":20}
Ponto final
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Salve list_bulk_jobs.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200Página de trabalho do Bulk
401Autenticação necessária ou inválida
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Pause um trabalho

Pausar novas submissões e empacotamento de resultados. Os trabalhos existentes continuam com as configurações e cargas originais. Retomar o trabalho quando estiver pronto.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Salve pause_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200Trabalho em massa em pausa ou seu estado idempotente atual
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Atualizar opções de trabalho

Atualizar as opções enquanto aguarda o upload, ou enquanto pausado antes que todas as entradas sejam lidas. Os trabalhos existentes mantêm suas configurações. Se a pausa ainda estiver em andamento, espere e tente novamente uma resposta 409. Depois de todas as informações terem sido lidas, apenas credenciais de entrega podem ser atualizadas. Defina callback_url para null para removê-lo.

Este exemplo remove a chamada completa. Para mudar as opções de origem, envie um objeto de opções. Pause primeiro e espere que a pausa faça efeito, um 409 significa que a atualização não pode ser aplicada ainda. trabalhos existentes mantêm suas opções originais.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salve update_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas e pedido de esquema

HTTP statusO que quer dizer?
200Estado de trabalho em massa atualizado
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
409Estado de recursos ou conflito de indemnidade
422A validação do pedido falhou
Corpo da requisição
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Retomar um trabalho

Corrigir pauseReason primeiro, como adicionar créditos ou atualizar credenciais de armazenamento, em seguida, retomar o mesmo Bulk ID.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Salve resume_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200O estado atual do trabalho em massa
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Cancele um trabalho

Parem as novas submissões. trabalhos existentes podem continuar finish e incorrer em suas cargas normais. Um trabalho cancelado não publica um manifesto final.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salve cancel_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200O estado atual do trabalho em massa
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Pegue o manifesto do resultado

Siga o redirecionamento para baixar o manifesto JSON e use seus links para recuperar arquivos de resultados. Traga o URLs sem sua chave API. Os resultados permanecem disponíveis para 24 horas após todo o trabalho Bulk terminar.

O pedido API autenticado retorna 302 com um cabeçalho de localização. Traga o HTTPS de armazenamento URL em um pedido separado sem X-API-Key. O exemplo salva manifest.json. Um 409 significa que os resultados não estão prontos, 410 significa que expiraram.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Ponto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Salve bulk_manifest.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200O manifesto JSON foi baixado após o redirecionamento
302Redirecionar para um R2 URL privado de curta duração; As credenciais API não devem ser enviadas. · Location
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
409Estado de recursos ou conflito de indemnidade
410O resultado retido expirou
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Descarregue as peças dos resultados

Use cada parts[].number de manifest.json. Cada endpoint retorna um 302 para um arquivo NDJSON gzip; download sem a chave API, descompressão, e então processar um objeto JSON por linha. Junte-se ao índice de zero. O exemplo recupera todas as partes e mantém arquivos ndjson.gz e .ndjson.

ParâmetroLocalizaçãoRequisição
bulkIdpathObrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathObrigatório · {"type":"integer","minimum":0}
Ponto final
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Salve bulk_parts.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.

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

Respostas

HTTP statusO que quer dizer?
200NDJSON comprimida por Gzip baixado após o redirecionamento
302Redirecionar para um R2 URL privado de curta duração; As credenciais API não devem ser enviadas. · Location
401Autenticação necessária ou inválida
404O recurso não foi encontrado ou não pertenceu ao chamador.
409Estado de recursos ou conflito de indemnidade
410O resultado retido expirou
200 · application/x-ndjson
{
  "type": "string"
}

O trabalho está em estado de retenção

Os resultados permanecem disponíveis para 24 horas após todo o trabalho Bulk terminar. Salve-os antes de expiresAt. A mídia no seu destino segue a política de retenção do seu balde. Um trabalho completo pode incluir vídeos fracassados, registros counts.invalid rejeitaram linhas de entrada.

EstadoPróxima ação
awaiting_uploadCarregue o arquivo e ligue para começar.
runningPesquise o mesmo ID com backoff, input.complete mostra se a varredura terminou.
pausedLeia pauseReason, conserte, e depois retome.
finalizingEspere o resultado da embalagem e a publicação do manifesto.
completedBaixe o manifesto e todas as partes. Inspecione o status e erro de cada linha.
failed / cancelledInspecione erro e estado salvo. Nenhum manifesto final é publicado.

Entrega de armazenamento

Use o playground para configurar um provedor e visualizar os campos exatos de solicitação. Credenciais de armazenamento de clientes pertencem ao objeto de armazenamento escolhido; X-API-Key autentica apenas pedidos FlashData API.

FonteCriar campo de solicitaçãoEntrega
Metadados, transcrição, legendas, verificação de licençaoptions.result_storageOpcional. Cópias NDJSON e um manifesto para o seu balde.
youtube_downloadoptions.storageNecessário. Entrega mídia ao seu balde, result_storage e browser_delivery não são aceitos.

Encontre os arquivos entregues

O manifesto de dados está escrito por último e lista as chaves de objetos, tamanhos e SHA-256 verificações. Difere do manifesto FlashData, que lista os valores de API href. YYYYMMDD em caminhos de dados usa a data de criação UTC Bulk; em caminhos de mídia usa a data de upload UTC de cada vídeo. Bulk OSS entrega de dados requer um ponto final aliyuncs.com.

Os valores de file_url precisam de seu armazenamento SDK ou um URL assinado por esse provedor. Uma chave FlashData não dá acesso ao balde. Os metadados opcionais são armazenados ao lado da mídia. Retornos de entrega aparecem em delivery.retryCount.

Disposição do objeto de dados
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Receba um webhook completo

Coloque um HTTPS callback_url público fora das opções. Bulk envia concluído apenas após publicar o manifesto; não envia eventos por vídeo e nenhum evento de conclusão para trabalhos fracassados ou cancelados. Mantenha o status das pesquisas como um retrocesso.

  1. Persista e deduplique delivery_id, e devolva 2xx imediatamente. A entrega retorna até oito vezes com retrocesso.
  2. Os eventos não estão assinados. Match id e fonte para o seu recibo salvo, verificar concluído através da gestão autenticada API antes de retirada em fila. Ignore URLs de um evento não verificado.
Faça um pedido com uma chamada de volta
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Evento de conclusão · 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"
    }
  ]
}

Esquema definições

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