# La tua prima trascrizione

> Parti da una chiave API e trascrivi un video da link o un file. Trovi esempi pronti per cURL, Python e Node.js.

Canonical: https://transcript1.com/it/docs/getting-started
Language: it
Last updated: 2026-10-14

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](https://transcript1.com/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”](https://transcript1.com/dashboard/account/tokens) 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`:

```bash
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](https://transcript1.com/it/docs/sources-and-options) 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

```bash
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

```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`.

```javascript
// 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](https://transcript1.com/it/docs/sources-and-options).

## 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:

```json
{
  "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:

```bash
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`:

```bash
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a
```

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](https://transcript1.com/it/docs/uploads).

## Continua con l'integrazione

- [Link e opzioni di trascrizione](https://transcript1.com/it/docs/sources-and-options): scegli sottotitoli o IA, lingua e riconoscimento dei parlanti.
- [Caricare file](https://transcript1.com/it/docs/uploads): invia un file intero o dividilo in parti.
- [Webhook](https://transcript1.com/it/docs/webhooks): ricevi un POST firmato al termine della trascrizione.
- [Server MCP](https://transcript1.com/it/docs/mcp): collega Claude, ChatGPT, Cursor, VS Code o Claude Code.
- [Endpoint API](https://transcript1.com/it/docs/api-reference): consulta parametri ed esempi per ogni chiamata.