Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Riferimento API

YouTube Captions API

Ottieni una chiave API

Recuperare le didascalie YouTube come testo timestamp e una trascrizione completa. Le didascalie fornite dal caricatore vengono selezionate per impostazione predefinita.

Crea una richiesta

L’ID di 11 caratteri presente nell’URL del video, non l’URL completo.

Lascia vuoto per provare prima en-orig, poi en, e ottenere una traccia. Oppure inserisci da uno a 10 codici distinti separati da virgole.

Traccia di cattura auto
POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_captions",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": False,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
Risultati nella risposta HTTPautenticazione X-API-Key

Parametri

Invia source e video_id al livello superiore. Le opzioni di origine appartengono in params. I campi opzionali possono essere omessi.

Corpo della richiesta

sourcestring / Obbligatorio
Impostare su youtube_captions.
video_idstring / Obbligatorio
Il video 11-character YouTube video ID, come FUfGcZ092b0. Accetta lettere, numeri, sottolineature e trattini.
Esattamente. 11 caratteriPredefinito: Non impostato
Formato accettato^[A-Za-z0-9_-]{11}$
paramsobject / Facoltativo
Settings per questa richiesta.
Predefinito: {}
callback_urlstring · nullable / Facoltativo
Async e solo lotto. Completamento HTTPS pubblico URL sulla porta 443, fino a caratteri 2,048. Nessuna credenziali utente o frammentazione URL. Omit, utilizzare null o una stringa vuota per nessuna notifica. In un lotto, impostare questo su ogni query, param esterni.
Predefinito: Non impostato

Selezione di acquisizione

params.languagestring | array / Facoltativo
Omit per l'inglese (en-orig, poi en). Con auto=true, ogni codice prova prima la sua traccia -orig, poi il codice richiesto. Codici espliciti -orig e auto=false rimangono esatti. Arrays richiedono lingue distinte 1–10.
Predefinito: en-orig → en
params.autoboolean / Facoltativo
true seleziona le didascalie generate da YouTube; false seleziona le didascalie fornite dal caricatore. Questo seleziona l'origine didascalia, non il rilevamento della lingua o la nuova trascrizione.
true o falsePredefinito: false

Risposta

Realtime restituisce status: done. Leggi l'output sorgente results[0]; usage.credits registra l'accusa.

Leggi i segmenti per il testo didascalia con start/end tempi in secondi e fullText per il testo unito. languageCode e isAutoGenerated segnalare la traccia selezionata.

Leggi il risultato

Salvare la risposta di successo JSON come response.json. Salvare questo come read-response.py ed eseguire pitone read-response.py. Utilizza solo la libreria standard di Python e non fa nuove richieste.

read-response.py
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))

Omit lingua per preferire en-orig e rientrare a en, tornando una traccia. Con auto=true, ogni codice richiesto preferisce la sua -orig traccia, quindi il codice normale; esplicito -orig e auto=false soggiorno esatto. languageCode identifica la traccia selezionata; requestedLanguageCode è incluso quando differisce.

Per gli elenchi di lingue, consulta errors per individuare le tracce non recuperate. Se non viene recuperata alcuna traccia, la richiesta non va a buon fine e i crediti riservati vengono rimborsati. Anche un errore di estrazione del video o la scadenza del tempo limite fanno fallire la richiesta.

auto default a false per le didascalie fornite dal caricatore. Impostare true per le didascalie automatiche. La API non commuta mai le fonti di didascalia.

La API legge le didascalie YouTube esistenti; non genera nuove trascrizioni. La risposta predefinita contiene segmenti JSON normalizzati; Accept può selezionare il testo normale e X-Respond-With: il markdown seleziona Markdown. languageName può essere null; i tempi dei segmenti sono conservati.

Lingue multiple

Inviare un array di lingua per ricevere tracce e errori per lingua. Questo esempio mostra l'inglese disponibile e lo spagnolo non disponibile.

Richiesta
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
results[0]
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": false,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Uploader-provided subtitles not available for language: es"
    }
  ]
}
Tutti i campi di risposta
Campo di applicazioneDesignazione
sourcestringLa fonte API richiesta.
statusstringfatto quando la richiesta in tempo reale riesce.
created_atstringTempo di creazione di risposta in formato ISO 8601.
usage.creditsnumberCrediti a carico della richiesta, in base al tuo piano.
results[0].videoIdstringIl video richiesto ID.
results[0].languageCodestringCodice traccia didascalia selezionato effettivo, come en-orig.
results[0].languageNamestring · nullableNome della visualizzazione della lingua quando disponibile.
results[0].requestedLanguageCodestring · optionalIl codice richiesto quando differisce da languageCode, per esempio en quando en-orig è stato selezionato.
results[0].isAutoGeneratedbooleanSe le didascalie selezionate sono state generate automaticamente.
results[0].segmentsarraySegmenti di cattura in ordine cronologico.
results[0].segments[].startnumberTempo di inizio del segmento in pochi secondi.
results[0].segments[].endnumberTempo di fine segmento in pochi secondi.
results[0].segments[].textstringTesto di acquisizione.
results[0].fullTextstringTutto il testo del segmento è entrato in una trascrizione.
results[0].tracksarray · optionalSolo per i sistemi linguistici. Le tracce disponibili in ordine di richiesta; ognuna ha i campi a binario singolo elencati sopra.
results[0].errorsarray · optionalSolo per i sistemi linguistici. Lingue non richieste in ordine. Vuoto quando ogni traccia riesce.
results[0].errors[].languageCodestringLa lingua richiesta che ha fallito.
results[0].errors[].codestringlanguage_unavailable quando la traccia selezionata non esiste; retrieval_failed quando non può essere scaricata o analizzata.
results[0].errors[].messagestringDescrizione del guasto linguistico.

I campi sopra descritti descrivono la risposta predefinita JSON. formati JSON, testo semplice e Markdown.

Async restituisce una ricevuta di lavoro; il lotto restituisce uno per video ID. Controllare lo stato di ogni lavoro e recuperare i risultati utilizzando i link restituiti.

Async & ciclo di vita in batch

La sottomissione restituisce una ricevuta, non i risultati. Async crea un lavoro; batch restituisce un lavoro separato in queries[] per ogni domanda accettata. Tracciare e recuperare ogni lavoro in modo indipendente.

Inviare a data.flashdata.dev; leggi lo stato del lavoro e i risultati ottenuti api.flashdata.dev con lo stesso X-API-Key. Gli esempi di base API collegati utilizzano Python e cURL.

  1. 1. Salvare il lavoro IDs

    Mantenere i campi di richiesta di questa fonte quando si passa a Async. Per Batch, inserire ogni richiesta all'interno dell'array query di un oggetto JSON. Salvare ogni lavoro restituito ID.

    Async richiesta e ricevuta · Corpo di richiesta Batch

  2. 2. Controllare lo stato

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing: sondaggio con ritardo e rispetto Retry-After quando presente. completed: risultati di ricerca. failed: ispezione job.error.

    Leggi job.status, non lo stato della ricevuta di presentazione.

    Stato di controllo · Python e cURL

    Stato del lavoro API riferimento
  3. 3. Risultati di riduzione

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    Dopo il completamento, autenticare il risultato letto, quindi prendere il 302 di archiviazione URL senza la chiave API. Salvare la JSON entro le ore di completamento 24.

    Risultati di riduzione · Python e cURL · Formati di risposta

    Risultato download API riferimento

L'inquinamento e l'ottenimento dei risultati esistenti non consumano i crediti di query. Un timeout inquinante non cancella il lavoro: mantieni il suo ID invece di presentare il lavoro duplicato fatturabile. Codici di errore e comportamento di riprovazione.

Webhook di completamento

Iscriviti per query

Set Set callback_url al livello superiore di una richiesta asincrona, o dentro ogni query in un lotto, fuori params. Non è richiesta alcuna richiesta di registrazione webhook separata. Le richieste di Realtime non inviano i callback.

Utilizzare un HTTPS URL pubblico sulla porta 443. FlashData POSTs una notifica per ogni lavoro che raggiunge completed o failed; l'evento contiene collegamenti, non il risultato stesso.

Riconoscimento e verifica

Ritorno 2xx dopo aver accettato duramente l'evento. Deduplicato da delivery_id, anche inviato come X-Delivery-Id. I reindirizzamenti non sono seguiti.

Recuperare le consegne non effettuate con backoff esponenziale, fino a 8 tenta totale e al massimo 24 ore dopo il completamento. Continua a inquinare come un fallback.

Le chiamate non sono firmate. Confermare il lavoro ID, lo stato sorgente e terminale attraverso endpoint di stato autenticato prima di elaborare la notifica. La consegna ID è per la deduplica, non la prova di autenticità.

Esempio webhook evento e campi
Notifica di completamento illustrativa
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "youtube_captions",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
      "method": "GET"
    }
  ]
}
Campo di applicazioneDesignazione
delivery_idstringIdentificatore di consegna stabile. Deduplicare le notifiche utilizzando questo valore; viene inviato anche nell'intestazione X-Delivery-Id.
idstringLavoro ID.
sourcestringFonte di dati richiesta.
statusstringcompletato o fallito.
linksarrayCollegamenti di stato e di risultato. Le notifiche non includono il contenuto dei risultati o una chiave API.
links[].relstringauto o risultati.
links[].hrefstringGestione assoluta API URL; autenticare con la chiave API.
links[].methodstringGET.

Contratto completo di webhook e restrizioni URL

Trattamento file Bulk

Caricare un video ID per linea e creare il lavoro Bulk con la fonte: youtube_captions. Le opzioni condivise si applicano a ogni ID nel file.

Opzioni di origine: lingua, auto. Mettile in opzioni quando si crea il lavoro Bulk.

Recuperare la collezione completa come parti di risultato NDJSON e gzip-compresse. Le fonti di dati possono anche fornire parti di risultato al cloud storage impostando options.result_storage quando si crea il lavoro Bulk. Salvare il manifesto e le parti all'interno di 24 ore dopo che l'intero lavoro Bulk è completato.

Bulk che elabora API · Python e cURL · richieste Batch JSON

Costruire un flusso di lavoro Bulk per questa sorgente · Pausa, riprendere e recuperare

Recupero di errore

Un video può avere didascalie automatiche, ma nessuna traccia manuale, o manca la lingua richiesta. Controllare la disponibilità didati utilizzando Metadata e scegliere la lingua e l'origine deliberatamente prima di una nuova presentazione.

Controlla le lingue didascalia disponibili con Metadata. Una nuova richiesta utilizza i crediti di query; la modifica di una traccia non modifica un lavoro esistente.

Per l'autenticazione, l'equilibrio, il formato delle richieste e i guasti dei limiti di velocità, utilizzare il riferimento di errore condiviso. Un timeout di presentazione può ancora aver creato un lavoro; controllare il lavoro esistente prima di riprovare.

Errori e codici di stato · Quando riprova · Limiti di tasso

Guida passo-passo: Recuperare le capzioni timestamp

Prezzi

PianiTassi di utilizzoper 1.000 richieste standardAbbonamentiCrediti inclusi per periodo di fatturazione
A consumo0,50 USDNessun canone mensileRicarica quando serve
Micro0,40 USD49,00 USD / meseCrediti 1000 (50,00 USD dell'utilizzo API) inclusi
Starter0,35 USD199,00 USD / meseCrediti 4000 (200,00 USD dell'utilizzo API) inclusi
Pro0,30 USD499,00 USD / meseCrediti 10.000 (500,00 USD dell'utilizzo API) inclusi
Scale0,25 USD999,00 USD / meseCrediti 20.000 (1000,00 USD dell'utilizzo API) inclusi
Business0,20 USD1999,00 USD / meseCrediti 40.000 (2000,00 USD dell'utilizzo API) inclusi

Un piano per account. Crediti condivisi tra i tre prodotti. L’utilizzo coperto dai crediti inclusi non viene addebitato nuovamente.

I prezzi attuali e i limiti del piano