La tua prima trascrizione

Per usare https://api.transcript1.com, aggiungi la tua chiave API nell'header Authorization. Qui trovi i passaggi per ottenere la chiave, avviare una trascrizione e leggerne il testo.

1. Registrati e genera la chiave API

Apri /signup e registrati con email, Google o Microsoft. Dopo la conferma dell'email hai 60 minuti gratis per iniziare: li ricevi una sola volta per account, senza carta. Se scegli Google o Microsoft, i minuti sono disponibili subito.

Nella dashboard, apri “API keys” all'indirizzo /dashboard/account/tokens e crea una chiave. Copiala subito: inizia con t1_ e non potrai visualizzarla di nuovo. Salvala nella variabile TRANSCRIPT1_API_KEY:

export TRANSCRIPT1_API_KEY="t1_..."

2. Invia il link del video

Puoi usare un link di YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn o Snapchat. Consulta Link e opzioni di trascrizione per sapere quali registrazioni pubbliche accettiamo e con quali limiti. Non occorre specificare platform: l'API riconosce la piattaforma dal link. Negli esempi usiamo YouTube.

Chiama POST /v1/transcriptions con l'URL del video. Aggiungi wait=60 alla query per aspettare fino a 60 secondi nella stessa chiamata. La risposta conferma la creazione, ma non contiene il testo: nell'esempio Python lo recuperi a parte con GET /v1/transcriptions/:id?wait=60. L'SDK per Node.js legge la chiave da TRANSCRIPT1_API_KEY e gestisce da solo l'attesa.

cURL

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Python

import os
import requests
 
headers = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
response = requests.post(
    "https://api.transcript1.com/v1/transcriptions?wait=60",
    headers=headers,
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
)
response.raise_for_status()
transcription = response.json()
while True:
    transcription = requests.get(
        f"https://api.transcript1.com/v1/transcriptions/{transcription['id']}?wait=60",
        headers=headers,
    ).json()
    if transcription["status"] in ("completed", "failed", "canceled"):
        break
 
if transcription["status"] == "completed":
    print(transcription["transcript"]["text"])
else:
    print(transcription["status"], transcription["error"])

Node.js

Per eseguire l'esempio, salvalo in index.mjs e lancia node index.mjs. Se preferisci un file .js, imposta "type": "module" nel package.json.

// npm i @transcript1/sdk
import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1();
const transcription = await t1.transcribe('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(transcription.transcript.text);

Di default, transcript1 cerca sottotitoli nella lingua originale su YouTube, X, TikTok, Bluesky, Dailymotion e LinkedIn. Se non trova una traccia che può usare, trascrive l'audio con IA. Per YouTube e X il comportamento resta invariato. Fuori da YouTube, i sottotitoli forniscono i timestamp dei segmenti, non delle singole parole.

Con source=stt o il riconoscimento dei parlanti, usi direttamente l'audio. La modalità captions (solo sottotitoli), invece, non scarica audio e non avvia STT. Per scegliere la modalità adatta, consulta Link e opzioni di trascrizione.

3. Recupera la trascrizione

Il codice HTTP ti dice se devi ancora aspettare:

• Con 200, la trascrizione ha raggiunto uno stato finale durante l'attesa: completed, failed o canceled.
• Con 202, sta ancora lavorando. Richiama GET /v1/transcriptions/:id?wait=60: ogni chiamata aspetta fino a 60 secondi. Continua finché status non indica uno stato finale.

Ecco un esempio abbreviato di trascrizione completata:

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "completed",
  "transcript_source": "youtube_captions",
  "language": "en",
  "billed_minutes": 4,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "speakers": [],
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." },
      { "start": 4.2, "end": 9.8, "speaker": null, "language": "en", "text": "Today we are looking at how transcripts are made." }
    ]
  }
}

Leggi tutto il testo in transcript.text. In transcript.segments trovi i singoli segmenti, con inizio (start) e fine (end) in secondi.

Per scaricare testo semplice o sottotitoli, scegli tra text, srt e vtt. Per esempio:

curl "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

La chiamata è GET /v1/transcriptions/:id?format=srt. Ricevi il formato scelto solo quando lo stato è completed. Prima di allora, l'API restituisce l'oggetto JSON con lo stato corrente.

4. Trascrivi un file

Hai il file sul computer? Fino a 95 MB puoi inviarlo con una sola chiamata multipart/form-data:

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected]

Per file più grandi, fino a 2 GB, usa il caricamento in parti: se si interrompe, riprendi dalle parti mancanti. Trovi la procedura in Caricare file.

Continua con l'integrazione

• Link e opzioni di trascrizione: scegli sottotitoli o IA, lingua e riconoscimento dei parlanti.
• Caricare file: invia un file intero o dividilo in parti.
• Webhook: ricevi un POST firmato al termine della trascrizione.
• Server MCP: collega Claude, ChatGPT, Cursor, VS Code o Claude Code.
• Endpoint API: consulta parametri ed esempi per ogni chiamata.