Link e opzioni di trascrizione

Puoi partire da un link di YouTube, X, TikTok, Instagram, Facebook o Bluesky, oppure da un file. Nella tabella trovi anche le altre piattaforme accettate e i link da usare per le registrazioni pubbliche.

Nel body di POST /v1/transcriptions puoi aggiungere source per scegliere tra sottotitoli e audio, diarize per il riconoscimento dei parlanti e language per la lingua. Sono tutti facoltativi.

Piattaforme supportate

Inserisci il link in url: l'API capisce da sola di quale piattaforma si tratta. Puoi anche specificare platform, purché corrisponda al link.

Per Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat, il link deve usare HTTPS, senza credenziali né porte personalizzate. Deve portare a una singola registrazione pubblica: niente post privati o che richiedono il login, dirette ancora in corso o in elaborazione, profili, feed o raccolte. Non inviamo cookie di account alla piattaforma. I parametri temporali del link non accorciano la registrazione. Con le clip Twitch e Snapchat Spotlight, media_id può essere una stringa opaca: salvala senza modificarla e non tentare di ricostruire l'ID dall'URL.

Su X, TikTok, Instagram, Facebook e Bluesky, scegli un post pubblico. Se contiene più video, trascriviamo solo il primo. Non funzionano profili, storie, pagine di dirette o post fotografici di TikTok. Se serve il login, ricevi login_required; se manca la traccia audio, ricevi no_audio. In entrambi i casi non paghi.

Su YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn possiamo usare i sottotitoli, ma solo se il video ha una traccia adatta nella lingua originale. Su Instagram, Facebook, Twitch, Pinterest e Snapchat trascriviamo sempre l'audio con IA: scegli auto o stt, non captions. Il prezzo al minuto è identico per tutte le piattaforme e per i file, e dipende dalla durata misurata.

Per i link brevi, attieniti ai formati della tabella. Se al momento dell'invio il link di condivisione non contiene l'ID del post, non possiamo abbinarlo a una trascrizione precedente. Per riutilizzare le trascrizioni, preferisci il link completo del post.

Quali link YouTube usare

Metti il link del video in url e lascia fuori platform, oppure usa youtube. Accettiamo questi formati, sia con www. sia senza:

Non serve ripulire il link: ignoriamo parametri come t, list e si e riconosciamo lo stesso video in tutti i formati. Serve però l'URL completo, non il solo ID di 11 caratteri. Con pagine di canali, link a sole playlist o link non supportati ricevi 422 invalid_url. Se platform ha un valore sconosciuto, ricevi 422 unsupported_platform e l'elenco supported_platforms.

Il video deve essere pubblico o non in elenco. Per i video privati, con limiti di età o ancora in diretta ricevi rispettivamente media_private, age_restricted o live_stream. Se hai il file, puoi caricarlo direttamente.

source

Con source scegli se leggere i sottotitoli già presenti o trascrivere l'audio.

Per i file, la trascrizione parte sempre dall'audio. Puoi impostare source su auto o stt; con captions ricevi 422 invalid_request.

La traccia deve essere nella lingua richiesta, oppure in quella originale del video se language è auto. Su YouTube usiamo sottotitoli caricati dal creator o generati da YouTube in quella lingua, mai traduzioni automatiche. Scegliamo prima quelli del creator, poi le tracce di origine sconosciuta e infine quelle generate automaticamente. Una traccia di origine sconosciuta non va attribuita al creator.

Su X usiamo le tracce VTT disponibili: hanno i timestamp dei segmenti, ma mai quelli delle parole, anche quando i sottotitoli sono generati automaticamente. In modalità auto passiamo a STT se il contenuto della traccia manca o non si riesce a interpretarlo. Non lo facciamo per errori di routing, storage o programmazione. Con stt saltiamo sempre i sottotitoli.

diarize

Attiva diarize per il riconoscimento dei parlanti. Di default vale false.

• Per distinguere chi parla serve la trascrizione dell'audio. Con source su auto e diarize: true, l'API avvia direttamente lo speech-to-text.
• Non abbinare source: "captions" a diarize: true: riceveresti 422 invalid_request.
• Trovi etichette come Speaker 1 e Speaker 2 in transcript.speakers e nel campo speaker di ogni segmento. Nei formati text e srt il testo ha il prefisso Speaker 1: ; in vtt c'è il tag voce <v Speaker 1>.

{ "platform": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ", "source": "stt", "diarize": true }

language

Lascia language su auto, il valore predefinito, oppure indica un codice ISO 639-1 di due lettere, come en, de o es.

• Se usi i sottotitoli, language seleziona la lingua della traccia. Con auto scegliamo quella originale del video.
• Se usi lo speech-to-text, il provider riceve la lingua come suggerimento. Con auto la rileva da solo e ogni segmento riporta la propria language.

Nel campo language dell'oggetto trascrizione trovi la lingua prevalente.

Da dove arriva il testo e quali dati ricevi

Controlla transcript_source per sapere da dove arriva il testo: youtube_captions, x_captions, tiktok_captions, bluesky_captions, dailymotion_captions, linkedin_captions o speech_to_text. Per i sottotitoli trovi anche caption_kind: manual, auto_generated oppure null. Quest'ultimo indica un'origine sconosciuta, non sottotitoli caricati dal creator.

Conserviamo i sottotitoli di YouTube senza riscriverli, anche se contengono tag come [Music]. Per lo speech-to-text, la registrazione può durare fino a 5 ore; oltre questo limite ricevi media_too_long.

Per X (x_captions), TikTok, Bluesky, Dailymotion e LinkedIn ricevi solo i timestamp dei segmenti e nessuna etichetta dei parlanti. Anche per le tracce automatiche, include=words restituisce words: null in ogni segmento. Se ti servono i timestamp delle parole, scegli source: "stt". Per il riconoscimento dei parlanti, attiva diarize: true con auto o stt.

Quanto costa

Il prezzo non cambia tra sottotitoli e speech-to-text: consumi un credito per ogni minuto di registrazione, arrotondando per eccesso. Cambia l'origine del testo, non il costo. I dettagli sono in Costi e limiti.