Explorar documentação
Referência da API
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.
Construir um fluxo de trabalho Bulk
Arquivo UTF-8 local, um YouTube ID por linha, até 2 GiB. Requisitos de entrada.
Deixe em branco para tentar en-orig e depois en, retornando uma faixa. Ou digite de um a 10 códigos diferentes, separados por vírgulas.
Resultado da entrega
Deixe isso fora para recuperar resultados através do FlashData API.
Bulk completando webhook
Notificação e verificação de completamento do manifestohttps://api.flashdata.dev/v2/bulk-jobsPonto 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étodo | Caminho | Ação |
|---|---|---|
| POST | /v2/bulk-jobs | Criar um trabalho Bulk |
| POST | /v2/bulk-jobs/{bulkId}/start | Carregue e comece |
| GET | /v2/bulk-jobs/{bulkId} | Obter status de trabalho |
| GET | /v2/bulk-jobs | Lista de trabalhos |
| POST | /v2/bulk-jobs/{bulkId}/pause | Pause um trabalho |
| PATCH | /v2/bulk-jobs/{bulkId} | Atualizar opções de trabalho |
| POST | /v2/bulk-jobs/{bulkId}/resume | Retomar um trabalho |
| DELETE | /v2/bulk-jobs/{bulkId} | Cancele um trabalho |
| GET | /v2/bulk-jobs/{bulkId}/results | Pegue 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.
| Fonte | Opções compartilhadas |
|---|---|
| youtube_metadata | include_formats include_chapters |
| youtube_transcript | Linguagem, auto |
| youtube_captions | Linguagem, auto |
| youtube_trainability | Sem opções |
| youtube_download | Opções de mídia e destino de armazenamento |
python -m pip install requestsCriar campos de solicitação
| Campo | Tipo | Uso |
|---|---|---|
| source | string | Necessário. Uma fonte suportada para cada entrada ID. |
| options | object | Opções de fonte compartilhada. Fontes de dados podem definir result_storage; YouTube Download requer armazenamento. |
| callback_url | string | Chamada 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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYSalve bulk_create.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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.jsonRespostas e pedido de esquema
| HTTP status | O que quer dizer? |
|---|---|
| 201 | Bulk trabalho criado com um 15-minuto de upload direto URL |
| 401 | Autenticação necessária ou inválida |
| 422 | A validação do pedido falhou |
| 503 | Uma dependência necessária ou catálogo está temporariamente indisponível |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYSalve bulk_start.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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}"Respostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | Bulk começou ou seu estado atual idempotente |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
| 409 | Estado de recursos ou conflito de indemnidade |
| 422 | A validação do pedido falhou |
| 503 | Uma dependência necessária ou catálogo está temporariamente indisponível |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalve bulk_status.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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.jsonRespostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | Bulk trabalho estado |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| 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_KEYSalve list_bulk_jobs.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"Respostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | Página de trabalho do Bulk |
| 401 | Autenticação necessária ou inválida |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYSalve pause_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"Respostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | Trabalho em massa em pausa ou seu estado idempotente atual |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalve update_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"Respostas e pedido de esquema
| HTTP status | O que quer dizer? |
|---|---|
| 200 | Estado de trabalho em massa atualizado |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
| 409 | Estado de recursos ou conflito de indemnidade |
| 422 | A validação do pedido falhou |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYSalve resume_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"Respostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | O estado atual do trabalho em massa |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalve cancel_bulk_job.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"Respostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | O estado atual do trabalho em massa |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
{
"$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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYSalve bulk_manifest.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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.jsonRespostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | O manifesto JSON foi baixado após o redirecionamento |
| 302 | Redirecionar para um R2 URL privado de curta duração; As credenciais API não devem ser enviadas. · Location |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
| 409 | Estado de recursos ou conflito de indemnidade |
| 410 | O resultado retido expirou |
{
"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âmetro | Localização | Requisição |
|---|---|---|
| bulkId | path | Obrigatório · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Obrigatório · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYSalve bulk_parts.py em api-api/ ao lado de bulk-created.json. Copie o script completo e execute o comando abaixo dele.
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"
doneRespostas
| HTTP status | O que quer dizer? |
|---|---|
| 200 | NDJSON comprimida por Gzip baixado após o redirecionamento |
| 302 | Redirecionar para um R2 URL privado de curta duração; As credenciais API não devem ser enviadas. · Location |
| 401 | Autenticação necessária ou inválida |
| 404 | O recurso não foi encontrado ou não pertenceu ao chamador. |
| 409 | Estado de recursos ou conflito de indemnidade |
| 410 | O resultado retido expirou |
{
"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.
| Estado | Próxima ação |
|---|---|
| awaiting_upload | Carregue o arquivo e ligue para começar. |
| running | Pesquise o mesmo ID com backoff, input.complete mostra se a varredura terminou. |
| paused | Leia pauseReason, conserte, e depois retome. |
| finalizing | Espere o resultado da embalagem e a publicação do manifesto. |
| completed | Baixe o manifesto e todas as partes. Inspecione o status e erro de cada linha. |
| failed / cancelled | Inspecione 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.
| Fonte | Criar campo de solicitação | Entrega |
|---|---|---|
| Metadados, transcrição, legendas, verificação de licença | options.result_storage | Opcional. Cópias NDJSON e um manifesto para o seu balde. |
| youtube_download | options.storage | Necessá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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonReceba 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.
- Persista e deduplique delivery_id, e devolva 2xx imediatamente. A entrega retorna até oito vezes com retrocesso.
- 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.
{
"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"
}
]
}Esquema definições
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."
}
}
}