API dati YouTube | Documentazione API

# YouTube Data API

Query YouTube videos, channels, Shorts, comments, community posts, search results and stream metadata through 34 authenticated endpoints: 32 GET and 2 POST.

## Authentication

Use your API Hop API key in the authorization header. Availability depends on enabled gateways and API key permissions; documentation alone does not confirm production availability.

```http
Authorization: Bearer YOUR_API_KEY
```

## Requests and caption tasks

GET operations use query parameters without a request body. Stream V3 uses POST with an application/json body and no query parameters; send proxy_url only in that body. The version segment selects the YouTube interface version. Unknown or duplicate fields are rejected. Keep identifiers and pagination cursors as strings, including values larger than JavaScript can safely represent as numbers.

```bash
curl --get "https://api.apihop.ai/v1/youtube/web/channels/id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "channel_name=LinusTechTips"
```

## Responses

Synchronous endpoints preserve the native JSON response. Caption endpoints return success, data.id, data.status, data.result and requestId. The examples below are illustrative, not live results.

```json
{"code":200,"data":{"channel_id":"UCXuqSBlHAE6Xw-yeJA0Tunw"}}
```

## Billing and pagination

For synchronous requests: Prices are per successful request, not per returned item. Every page is a separate request. Most operations cost $0.001. The two V2 search variants cost $0.002; the V2 stream variant costs $0.004. See each endpoint below. Account-specific prices take precedence. Supplier volume discounts are not automatically passed through. Failed upstream calls release the reservation; settlement failures return an error and do not trigger a second upstream request.

## Caption tasks

POST https://api.apihop.ai/v1/youtube/web-v2/videos/captions returns HTTP 202 and a platform task ID, with Location: /v1/jobs/\{id\}. Query GET https://api.apihop.ai/v1/youtube/web-v2/videos/captions/result?job_id=\{id\} every 2–5 seconds. Only the owning tenant can read the task. Result queries are free; creation costs $0.008 at the list price. No-caption results are successful and billable. The format is fixed at creation (default srt); an optional result format must match or returns HTTP 400. data.result is null until COMPLETED; tasks may end as FAILED. These endpoints retrieve existing captions, not AI transcriptions.

If submission acceptance is uncertain, the request is not replayed and its reservation may remain held until the 30-minute task deadline. A supplier result may remain pending while settlement is reconciled. A transient polling error is not a terminal task failure.

```json
{"success":true,"data":{"id":"9007199254740993001","status":"PROCESSING","result":null},"requestId":"example"}
```

## Scope and limitations

The web and web-v2 paths select the upstream interface family. Stream V3 supports POST retrieval with your own fixed-exit HTTP proxy. Stream endpoints return metadata and URLs, not media files or guaranteed downloads. Channel descriptions may require a second separately billed request using continuation_token. No automatic retries are made.

Stream V3 uses POST JSON over HTTPS and costs $0.003 per successful request. Provide video_id and proxy_url (http:// with an explicit port and public host); private, loopback and link-local destinations are forbidden. URL-encode reserved characters in credentials. Use a fixed exit or sticky proxy session. itags defaults to ["137", "140"]; unavailable formats fail without substitution. verify_download defaults to false. Download through the same proxy session and actual public exit IP with streams[].download_headers. Successful URL extraction (HTTP 200) is billable even when all_selected_streams_verified or streams[].verified is false. Verification samples small byte ranges, not the complete file. URLs and proxy sessions expire independently; merge separate audio/video streams yourself.

## Reference

Select an endpoint and send only its documented fields. When alternatives are listed, provide at least one field from each group. Pagination values must come from the preceding response; there is no automatic pagination.

[Complete reference](https://apihop.ai/en/docs/api-reference/youtube/reference)

## Errors

Platform errors use HTTP 400 for invalid parameters, 401 for invalid authentication, 402 for insufficient credit, 403 for denied gateway access, 429 for rate limits, and 5xx for service or supplier failures. Keep X-Request-Id for troubleshooting. Do not treat an upstream HTTP 200 with a failed business code as success.

## Sources

The endpoint list and prices were checked against the official schema and live price metadata on 2026-10-31. Live metadata takes precedence over conflicting prose prices.

[TikHub](https://docs.tikhub.io/4592766m0) · [OpenAPI](https://api.tikhub.io/openapi.json) · [Prices](https://api.tikhub.io/api/v1/tikhub/user/get_all_endpoints_info)

Consulta video, canali, Shorts, commenti, post della community, risultati di ricerca e metadati dei flussi YouTube tramite 34 endpoint autenticati: 32 GET e 2 POST.

Autenticazione

Usa la chiave API API Hop nell’intestazione di autorizzazione. La disponibilità dipende dai gateway attivi e dai permessi della chiave; la documentazione non conferma la disponibilità in produzione.

http

Authorization: Bearer YOUR_API_KEY

Richieste e attività dei sottotitoli

Le operazioni GET usano parametri di query senza corpo. Il flusso V3 usa POST con un corpo application/json e senza parametri di query; invia proxy_url solo nel corpo. Il segmento di versione seleziona l’interfaccia YouTube. Campi sconosciuti o duplicati vengono rifiutati. Conserva identificatori e cursori come stringhe, anche oltre l’intervallo intero sicuro di JavaScript.

bash

curl --get "https://api.apihop.ai/v1/youtube/web/channels/id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "channel_name=LinusTechTips"

Risposte

Gli endpoint sincroni conservano la risposta JSON originale. Quelli dei sottotitoli restituiscono success, data.id, data.status, data.result e requestId. Gli esempi sono illustrativi, non risultati reali.

json

{"code":200,"data":{"channel_id":"UCXuqSBlHAE6Xw-yeJA0Tunw"}}

Fatturazione e paginazione

Per le richieste sincrone: Si paga per richiesta riuscita, non per elemento restituito. Ogni pagina è una richiesta distinta. La maggior parte delle operazioni costa $0.001. Le due varianti di ricerca V2 costano $0.002 e la variante dei flussi V2 $0.004. Il prezzo è indicato per ogni endpoint. I prezzi specifici dell’account hanno precedenza. Gli sconti del fornitore sui volumi non vengono trasferiti automaticamente. Un errore del fornitore libera la prenotazione; un errore di contabilizzazione non genera una seconda richiesta al fornitore.

Attività dei sottotitoli

POST https://api.apihop.ai/v1/youtube/web-v2/videos/captions restituisce HTTP 202, un ID di attività della piattaforma e Location: /v1/jobs/\{id\}. Consultare GET https://api.apihop.ai/v1/youtube/web-v2/videos/captions/result?job_id=\{id\} ogni 2–5 secondi. Solo il tenant proprietario può accedere. La consultazione è gratuita; la creazione costa $0.008 a listino. Un risultato senza sottotitoli è riuscito e fatturabile. Il formato è fissato alla creazione (srt predefinito); il format opzionale della consultazione deve coincidere, altrimenti si riceve HTTP 400. data.result è null fino a COMPLETED; è possibile anche FAILED. Si recuperano sottotitoli esistenti, senza trascrizione IA.

Se l’accettazione non è certa, la richiesta non viene ripetuta e la prenotazione può rimanere fino al termine di 30 minuti dell’attività. Il risultato può restare in attesa durante la riconciliazione della fatturazione. Un errore temporaneo di consultazione non equivale a un fallimento definitivo.

json

{"success":true,"data":{"id":"9007199254740993001","status":"PROCESSING","result":null},"requestId":"example"}

Ambito e limiti

web e web-v2 selezionano la famiglia di interfacce. Il flusso V3 supporta POST con un proxy HTTP proprio a uscita fissa. I flussi restituiscono metadati e URL, non file o garanzie di download. La descrizione di un canale può richiedere una seconda richiesta fatturata con continuation_token. Nessun tentativo automatico.

Il flusso V3 usa POST JSON via HTTPS e costa $0.003 per richiesta riuscita. Fornisci video_id e proxy_url (http:// con porta esplicita e host pubblico). Sono vietate destinazioni private, loopback e link-local; codifica i caratteri riservati delle credenziali. Usa un’uscita fissa o una sessione persistente. itags è ["137", "140"] per impostazione predefinita; i formati mancanti non vengono sostituiti. verify_download è false per impostazione predefinita. Scarica con la stessa sessione proxy, lo stesso IP pubblico effettivo e streams[].download_headers. L’estrazione riuscita degli URL (HTTP 200) è fatturata anche se all_selected_streams_verified o streams[].verified è false. La verifica legge piccoli campioni di byte, non l’intero file. URL e sessioni scadono indipendentemente; unisci i flussi audio e video separati nel client.

Riferimento

Invia solo i campi documentati per l’endpoint scelto. Per ogni gruppo di alternative, fornisci almeno un campo. I cursori provengono dalla risposta precedente; la paginazione non è automatica.

Riferimento completo

Errori

HTTP 400 indica parametri non validi, 401 autenticazione non valida, 402 saldo insufficiente, 403 accesso negato, 429 limiti di frequenza e 5xx errori del servizio o fornitore. Conserva X-Request-Id per la diagnosi. HTTP 200 con un codice applicativo di errore non indica successo.

Fonti

Endpoint e prezzi sono stati verificati il 2026-10-31 rispetto allo schema ufficiale e ai metadati di prezzo correnti. I metadati correnti prevalgono su indicazioni testuali contrastanti.

TikHub · OpenAPI · Prices