API di YouTube

L'API di YouTube ti permette di cercare su YouTube e recuperare metadati video attraverso un'unica interfaccia unificata. Ogni endpoint restituisce JSON strutturato con il monitoraggio del consumo di crediti.

Endpoint

Endpoint	Descrizione
`POST /api/v1/youtube/search`	Cerca su YouTube con filtri (data, durata, tipo, qualità)
`POST /api/v1/youtube/metadata`	Ottieni metadati strutturati per un video (visualizzazioni, mi piace, tag, descrizione)

Autenticazione

Intestazione	Valore	Obbligatorio
`Authorization`	`Bearer YOUR_API_KEY`	Sì
`Content-Type`	`application/json`	Sì

Ricerca su YouTube

Bash

POST https://api.scavio.dev/api/v1/youtube/search

Cerca su YouTube e ottieni risultati strutturati. Supporta il filtraggio per data di caricamento, durata, tipo di risultato, qualità video e altro.

Corpo della Richiesta

Parametro	Tipo	Predefinito	Descrizione
`search`	`string`	--	Obbligatorio. Query di ricerca (1-500 caratteri).
`upload_date`	`string`	--	Filtra per data di caricamento. Uno tra: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtra per tipo di risultato. Uno tra: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtra per durata video. Uno tra: `short` (sotto 4 min), `medium` (4-20 min), `long` (oltre 20 min)
`sort_by`	`string`	`relevance`	Ordine di ordinamento. Uno tra: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Solo video HD
`4k`	`boolean`	`false`	Solo video 4K
`subtitles`	`boolean`	`false`	Solo video con sottotitoli/didascalie
`creative_commons`	`boolean`	`false`	Solo video con licenza Creative Commons
`live`	`boolean`	`false`	Solo dirette streaming
`hdr`	`boolean`	`false`	Solo video HDR
`360`	`boolean`	`false`	Solo video a 360 gradi
`3d`	`boolean`	`false`	Solo video 3D
`location`	`boolean`	`false`	Solo video con metadati di posizione
`vr180`	`boolean`	`false`	Solo video VR180

Esempio

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

Esempio di Risposta

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

Metadati Video

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

Ottieni metadati strutturati per un video di YouTube inclusi titolo, descrizione, conteggio visualizzazioni, conteggio mi piace, conteggio commenti, tag, miniature, data di caricamento, informazioni sul canale e formati disponibili.

Corpo della Richiesta

Parametro	Tipo	Descrizione
`video_id`	`string`	Obbligatorio. ID video di YouTube (es. `dQw4w9WgXcQ`).

Esempio

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

Esempio di Risposta

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

Formato della Risposta

Tutti gli endpoint di YouTube restituiscono un wrapper di risposta coerente:

Campo	Tipo	Descrizione
`data`	`object \| null`	Il payload della risposta. La forma dipende dall'endpoint. La ricerca restituisce `{results, search}`; i metadati restituiscono l'oggetto video. `null` se la richiesta è fallita a monte.
`response_time`	`number`	Tempo di risposta lato server in millisecondi
`credits_used`	`number`	Numero di crediti consumati da questa richiesta
`credits_remaining`	`number`	Crediti rimanenti nel tuo attuale periodo di fatturazione

Risposte di Errore

Stato	Descrizione
`401`	Non autorizzato -- chiave API mancante o non valida
`429`	Limite di frequenza o di utilizzo superato per il tuo piano
`502`	Errore a monte -- riprova dopo un breve ritardo
`503`	Servizio a monte non disponibile -- riprova più tardi

Vedi Errori per il riferimento completo agli errori e le migliori pratiche per i tentativi.

Correlati

Guida rapida -- ottieni la tua chiave API e fai la tua prima richiesta
API di Ricerca Google -- cerca su Google con dati SERP strutturati
API Amazon -- cerca prodotti e ottieni dettagli per ASIN
Limiti di Frequenza -- limiti per livello di piano
Errori -- codici di errore e gestione

API di YouTube

Endpoint

Endpoint	Descrizione
`POST /api/v1/youtube/search`	Cerca su YouTube con filtri (data, durata, tipo, qualità)
`POST /api/v1/youtube/metadata`	Ottieni metadati strutturati per un video (visualizzazioni, mi piace, tag, descrizione)

Autenticazione

Intestazione	Valore	Obbligatorio
`Authorization`	`Bearer YOUR_API_KEY`	Sì
`Content-Type`	`application/json`	Sì

Ricerca su YouTube

Bash

POST https://api.scavio.dev/api/v1/youtube/search

Cerca su YouTube e ottieni risultati strutturati. Supporta il filtraggio per data di caricamento, durata, tipo di risultato, qualità video e altro.

Corpo della Richiesta

Parametro	Tipo	Predefinito	Descrizione
`search`	`string`	--	Obbligatorio. Query di ricerca (1-500 caratteri).
`upload_date`	`string`	--	Filtra per data di caricamento. Uno tra: `last_hour`, `today`, `this_week`, `this_month`, `this_year`
`type`	`string`	--	Filtra per tipo di risultato. Uno tra: `video`, `channel`, `playlist`
`duration`	`string`	--	Filtra per durata video. Uno tra: `short` (sotto 4 min), `medium` (4-20 min), `long` (oltre 20 min)
`sort_by`	`string`	`relevance`	Ordine di ordinamento. Uno tra: `relevance`, `date`, `view_count`, `rating`
`hd`	`boolean`	`false`	Solo video HD
`4k`	`boolean`	`false`	Solo video 4K
`subtitles`	`boolean`	`false`	Solo video con sottotitoli/didascalie
`creative_commons`	`boolean`	`false`	Solo video con licenza Creative Commons
`live`	`boolean`	`false`	Solo dirette streaming
`hdr`	`boolean`	`false`	Solo video HDR
`360`	`boolean`	`false`	Solo video a 360 gradi
`3d`	`boolean`	`false`	Solo video 3D
`location`	`boolean`	`false`	Solo video con metadati di posizione
`vr180`	`boolean`	`false`	Solo video VR180

Esempio

curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "langchain tutorial",
    "type": "video",
    "duration": "medium",
    "sort_by": "view_count",
    "upload_date": "this_year"
  }'

Esempio di Risposta

JSON

{
  "data": {
    "results": [
      {
        "videoId": "sVcwVQRHIc8",
        "title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
        "longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
        "publishedTimeText": { "simpleText": "1 year ago" },
        "lengthText": { "simpleText": "2:33:11" },
        "viewCountText": { "simpleText": "1,258,310 views" },
        "thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
      }
    ],
    "search": "langchain tutorial"
  },
  "response_time": 1230,
  "credits_used": 1,
  "credits_remaining": 999
}

Metadati Video

Bash

POST https://api.scavio.dev/api/v1/youtube/metadata

Corpo della Richiesta

Parametro	Tipo	Descrizione
`video_id`	`string`	Obbligatorio. ID video di YouTube (es. `dQw4w9WgXcQ`).

Esempio

curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"video_id": "sVcwVQRHIc8"}'

Esempio di Risposta

JSON

{
  "data": {
    "title": "Learn RAG From Scratch - Python AI Tutorial",
    "description": "Learn how to implement RAG from scratch...",
    "upload_date": 20240417,
    "duration": 9191,
    "view_count": 1258310,
    "like_count": 23211,
    "comment_count": 295,
    "categories": ["Education"],
    "tags": ["rag", "langchain", "python", "llm"],
    "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
    "channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
    "uploader": "freeCodeCamp.org",
    "uploader_id": "@freecodecamp",
    "uploader_url": "https://www.youtube.com/@freecodecamp",
    "video_id": "sVcwVQRHIc8",
    "is_live": false,
    "age_limit": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "formats": []
  },
  "response_time": 890,
  "credits_used": 1,
  "credits_remaining": 998
}

Formato della Risposta

Tutti gli endpoint di YouTube restituiscono un wrapper di risposta coerente:

Campo	Tipo	Descrizione
`data`	`object \| null`	Il payload della risposta. La forma dipende dall'endpoint. La ricerca restituisce `{results, search}`; i metadati restituiscono l'oggetto video. `null` se la richiesta è fallita a monte.
`response_time`	`number`	Tempo di risposta lato server in millisecondi
`credits_used`	`number`	Numero di crediti consumati da questa richiesta
`credits_remaining`	`number`	Crediti rimanenti nel tuo attuale periodo di fatturazione

Risposte di Errore

Stato	Descrizione
`401`	Non autorizzato -- chiave API mancante o non valida
`429`	Limite di frequenza o di utilizzo superato per il tuo piano
`502`	Errore a monte -- riprova dopo un breve ritardo
`503`	Servizio a monte non disponibile -- riprova più tardi

Vedi Errori per il riferimento completo agli errori e le migliori pratiche per i tentativi.

Correlati

Guida rapida -- ottieni la tua chiave API e fai la tua prima richiesta
API di Ricerca Google -- cerca su Google con dati SERP strutturati
API Amazon -- cerca prodotti e ottieni dettagli per ASIN
Limiti di Frequenza -- limiti per livello di piano
Errori -- codici di errore e gestione