> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Crea capitoli YouTube
> Genera capitoli con indicazioni temporali per un video YouTube e salva la cronologia dei capitoli. Restituisce un riferimento compatto al risultato salvato; usa il relativo getAction o downloadAction per recuperare l'output completo.
Genera capitoli con indicazioni temporali per un video YouTube e salva la cronologia dei capitoli. Restituisce un riferimento compatto al risultato salvato; usa il relativo getAction o downloadAction per recuperare l'output completo.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/youtube_chapters_create
```
## Autenticazione e autorizzazioni
Invia una chiave API VoiceCheap in questa intestazione. È supportato anche Authorization: Bearer con la stessa chiave API. I token di accesso OAuth
sono accettati solo da MCP, non da questo endpoint REST.
Autorizzazioni richieste: `transcription:write`.
È necessario un abbonamento a pagamento attivo. Le autorizzazioni non modificano i ruoli del team, la proprietà delle risorse, i crediti multimediali o i limiti del piano.
## Parametri
Valore testuale.
Lunghezza massima: 2048. Formato: "uri".
Facoltativo al livello di trasporto: se omesso, il server inserisce un identificatore prima della validazione. Fornisci un tuo UUID v4 stabile per recuperare in sicurezza una risposta persa.
Formato: "uuid". Pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`.
Il JSON Schema seguente conserva i nomi esatti dei campi, i tipi annidati, i valori predefiniti, i limiti e i valori accettati esposti dalla discovery. Le ulteriori regole tra campi sono elencate nelle note sull'operazione.
```json theme={null}
{
"type": "object",
"properties": {
"youtubeUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"requestId": {
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
"type": "string",
"format": "uuid",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
}
},
"required": ["youtubeUrl"],
"additionalProperties": false
}
```
## Idempotenza
Usa un UUID v4 in requestId o nell'intestazione HTTP Idempotency-Key per ogni modifica. Riutilizza lo stesso identificatore e argomenti identici dopo un errore di rete. Se vengono forniti entrambi, devono coincidere. Ripetere una richiesta salvata non ripete l'operazione e non consuma un'altra chiamata mensile. Le richieste non riuscite o interrotte non vengono riavviate automaticamente.
Ogni modifica può restituire HTTP 202 quando un nuovo tentativo trova la stessa richiesta ancora in esecuzione, anche se la prima esecuzione è normalmente sincrona. Se l'esecuzione è completata ma resultStored è false, un nuovo tentativo restituisce HTTP 200 con lo stato della richiesta salvata anziché il risultato originale. Recupera l'output tramite l'azione di cronologia, risultato o download del relativo dominio.
## Esempi di richiesta
Sostituisci gli identificatori delle risorse e le chiavi multimediali di esempio con i valori restituiti per il tuo account. Mantieni stabile l'identificatore della richiesta quando ripeti la stessa modifica.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/youtube_chapters_create' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"youtubeUrl":"https://www.youtube.com/watch?v=abcdefghijk","requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'
```
```javascript JavaScript theme={null}
const input = {
youtubeUrl: 'https://www.youtube.com/watch?v=abcdefghijk',
requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/youtube_chapters_create', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/youtube_chapters_create",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"youtubeUrl": "https://www.youtube.com/watch?v=abcdefghijk", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## Risposta
Questa operazione restituisce HTTP 202 mentre è in esecuzione. Salva requestId e interroga action\_request\_get con questo identificatore e il nome dell'operazione originale. Gli stati del polling sono running, completed, failed e interrupted. Un risultato completato può rimandare a un processo multimediale separato; prosegui con l'azione di stato o di output specifica dell'operazione.
Riferimento salvato ai capitoli YouTube. Il JSON completo contiene i metadati del video, chapters con startSeconds/timestamp/title, testo pronto da copiare, createdAt e, facoltativamente, language e generationId.
```json HTTP 202 theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 200 theme={null}
{
"data": {
"resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
"operation": "youtube_chapters_create",
"createdAt": 1792152000000,
"fileName": "voicecheap-youtube_chapters_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
"byteLength": 603,
"contentType": "application/json; charset=utf-8",
"status": "completed",
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"getAction": "transcription_result_get",
"downloadAction": "transcription_result_download",
"listAction": "transcription_result_list"
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_chapters_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_chapters_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```
## Campi del risultato
| Campo | Descrizione |
| - | - |
| `data.resultId` | UUID di un output salvato di proprietà dell'utente. Usalo con getAction o downloadAction; è distinto da requestId e da qualsiasi historyId. |
| `data.operation` | Azione di generazione che ha prodotto questo JSON salvato. |
| `data.createdAt` | Timestamp Unix in millisecondi della preparazione dell'output salvato. |
| `data.fileName` | Nome di file suggerito per un'esportazione JSON. |
| `data.byteLength` | Byte UTF-8 dell'output serializzato completo, non dei metadati compatti. |
| `data.contentType` | application/json; charset=utf-8. |
| `data.status` | completed quando la generazione riesce. La cronologia dei risultati può mostrare anche voci di recupero con stato pending. |
| `data.requestId` | UUID della richiesta di azione originale, quando registrato. |
| `data.getAction` | Azione di recupero di un elemento di proprietà dell'utente; il valore predefinito di includeContent è false e deve essere true per ottenere l'output strutturato completo. |
| `data.downloadAction` | Azione di esportazione autenticata che restituisce il JSON completo come stringa di contenuto. |
| `data.listAction` | Azione per elencare gli output salvati di tua proprietà in questo dominio di autorizzazioni. |
## Recupera e monitora questa richiesta
Usa lo stesso identificatore anche dopo una connessione persa. Se resultStored è false, recupera l'output tramite la corrispondente azione di cronologia, risultato o download. Non avviare mai una seconda generazione solo per verificarne l'avanzamento.
```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab","operation":"youtube_chapters_create"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"operation": "youtube_chapters_create",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b",
"operation": "youtube_chapters_create",
"createdAt": 1792152000000,
"fileName": "voicecheap-youtube_chapters_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json",
"byteLength": 603,
"contentType": "application/json; charset=utf-8",
"status": "completed",
"requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
"getAction": "transcription_result_get",
"downloadAction": "transcription_result_download",
"listAction": "transcription_result_list"
}
}
}
```
## Note sull'operazione
* Richiede un abbonamento a pagamento e l'autorizzazione dell'azione. Il piano personale del chiamante per gli strumenti viene ricontrollato al momento dell'esecuzione; gli strumenti salvati e i riferimenti ai caricamenti appartengono a quel chiamante, anche quando la credenziale è associata a un team.
* Un'azione riuscita consuma una chiamata mensile condivisa API/MCP. Beginner consente 500, Starter 5,000 e Creator 25,000 chiamate al mese; Pro, Scale ed Enterprise non hanno un limite mensile. Si applicano comunque i limiti al minuto: rispettivamente 30, 60, 120, 180, 300 e 600. Le quote di generazione degli strumenti sono separate.
* Usa un requestId UUID v4, oppure un header Idempotency-Key identico, e mantieni la stessa azione, lo stesso ID e gli stessi argomenti nei tentativi successivi. La ripetizione di un risultato memorizzato nella cache non consuma un'altra chiamata mensile.
* Questa è un'azione asincrona. Il risultato iniziale del trasporto è una richiesta running con pollAction; interroga periodicamente action\_request\_get con questa operazione e il requestId originale. Il risultato dell'operazione completata mostrato qui è un riferimento compatto all'output salvato, non il corpo generato.
* L'output completo viene salvato in un archivio cifrato con titolarità autenticata, indipendentemente dalla cache limitata del polling delle azioni. Chiama il getAction restituito con resultId e includeContent: true per il JSON strutturato, oppure downloadAction con resultId per il testo JSON. listAction offre una via di recupero quando è nota solo la richiesta originale.
* Il JSON salvato è limitato a 32 MiB. I metadati non espongono mai la chiave di crittografia dell'archiviazione né un URL di download della trascrizione senza autenticazione.
* Una generazione riuscita consuma definitivamente un'unità della quota personale dello strumento. Una generazione non riuscita normalmente libera la relativa prenotazione. Quando la persistenza dell'output è incerta, controlla la stessa richiesta e la cronologia dei risultati salvati prima di generare di nuovo; il server mantiene la prenotazione per evitare consumi duplicati.
* Anche i piani superiori senza limite mensile per le integrazioni hanno le quote giornaliere specifiche degli strumenti e i limiti multimediali riportati di seguito. Queste azioni autonome utilizzano la quota del relativo strumento anziché i minuti di doppiaggio o i caratteri TTS.
* Usa un URL HTTPS pubblico di un video YouTube. Il video deve durare almeno 30 secondi e al massimo 2 ore.
* Quota giornaliera di capitoli YouTube: Beginner 5, Starter 10, Creator 20, Pro 35, Scale 50 ed Enterprise 100; condivisa con lo strumento web per i capitoli.
* La quota per i capitoli viene prenotata immediatamente e ripristinata in caso di normale errore di esecuzione. Un output riuscito rimane conteggiato anche se si perde la conferma del conteggio definitivo.
* generationId è l'ID della cronologia dello strumento quando il relativo tentativo di salvataggio della cronologia riesce. Il resultId dedicato dell'integrazione rimane l'identificatore di recupero di proprietà dell'utente.
* I capitoli includono una stringa di timestamp e startSeconds numerico. Non viene utilizzato alcun fileKey di origine caricato in precedenza.
## Utilizzo
Ogni invocazione riuscita consuma una chiamata API/MCP mensile. Si applicano anche i crediti multimediali e le quote di generazione proprie dell'operazione.
## Errori
| Stato HTTP | Codice | Significato o risoluzione |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Le credenziali sono state fornite in un parametro di query access\_token o api\_key. Invia le credenziali negli header. |
| 400 | `DURATION_TOO_LONG` | Il video YouTube supera 7,200 secondi. |
| 400 | `DURATION_TOO_SHORT` | Il video è più breve del minimo di 30 secondi. |
| 400 | `DURATION_UNKNOWN` | Non è stato possibile determinare una durata positiva del video YouTube. |
| 400 | `IDEMPOTENCY_CONFLICT` | Gli ID della richiesta nell'header e nel corpo sono diversi. |
| 400 | `INVALID_REQUEST_ID` | requestId o Idempotency-Key non è un UUID v4. |
| 400 | `INVALID_YOUTUBE_URL` | L'URL HTTPS di YouTube non identifica un video supportato. |
| 400 | `VALIDATION_ERROR` | Gli argomenti non soddisfano lo schema dell'azione oppure è stato fornito un argomento sconosciuto. |
| 400 | `VIDEO_AGE_RESTRICTED` | Il video YouTube è soggetto a limiti di età. |
| 400 | `VIDEO_PRIVATE` | Il video YouTube è privato. |
| 400 | `VIDEO_REGION_BLOCKED` | Il video YouTube è bloccato nella regione del server. |
| 400 | `VIDEO_UNAVAILABLE` | Il video YouTube non è disponibile. |
| 401 | `API_KEY_EXPIRED` | La chiave API è scaduta. |
| 401 | `INVALID_API_KEY` | Fornisci una chiave API valida e non scaduta. |
| 401 | `INVALID_CREDENTIAL` | L'header Authorization non è valido oppure è in conflitto con x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Non è stata fornita alcuna credenziale utilizzabile negli header, oppure la credenziale superava 4096 caratteri. |
| 401 | `USER_NOT_FOUND` | L'account associato alla credenziale non esiste più. |
| 403 | `ACCOUNT_UNAVAILABLE` | L'account che esegue l'azione o quello di fatturazione non è disponibile o è in fase di eliminazione. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | L'utente della credenziale appartiene a più di un team, quindi il contesto di fatturazione è ambiguo. |
| 403 | `INSUFFICIENT_SCOPE` | La chiave API o la connessione MCP non dispone dell'autorizzazione richiesta per l'azione. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Impossibile verificare i limiti di integrazione dell'account. |
| 403 | `PAID_SUBSCRIPTION_REQUIRED` | L'utente autenticato non dispone più di un abbonamento a pagamento quando questa azione dello strumento viene eseguita. |
| 403 | `SUBSCRIPTION_REQUIRED` | Usa un abbonamento a pagamento attivo. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Non è stato possibile trovare l'account effettivo del proprietario del team. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Questo account ha già 10 azioni di integrazione in esecuzione. Interroga una richiesta esistente prima di avviarne un'altra. |
| 409 | `IDEMPOTENCY_CONFLICT` | Riutilizza un identificatore solo con la stessa operazione e gli stessi argomenti. |
| 410 | `TOOL_RESULT_ACCOUNT_UNAVAILABLE` | L'account dell'utente è in fase di eliminazione o non esiste più, quindi non è possibile salvare un risultato persistente. |
| 413 | `TOOL_RESULT_TOO_LARGE` | Il JSON generato completo supera 32 MiB e non può essere salvato come risultato di integrazione. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Le chiamate utilizzate e in attesa hanno raggiunto la quota mensile API/MCP condivisa. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | L'account ha raggiunto il limite di integrazione al minuto; controlla retryAfterSeconds. |
| 429 | `YOUTUBE_CHAPTERS_TOOL_DAILY_LIMIT_REACHED` | L'utente ha esaurito la quota giornaliera del generatore di capitoli. |
| 500 | `INTERNAL_ERROR` | Si è verificato un errore interno nello strumento originale o nella persistenza del risultato. Esamina la richiesta salvata e la cronologia degli output prima di riprovare una generazione. |
| 502 | `INTERNAL_ERROR` | La generazione o il salvataggio dell'output non è riuscito. Controlla la richiesta originale e la cronologia dei risultati salvati prima di avviare un'altra generazione. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | L'azione è stata eseguita, ma non è stato possibile confermare la memorizzazione del risultato della richiesta. Interroga periodicamente la stessa azione con lo stesso requestId e controlla la cronologia della risorsa prima di avviare un'altra scrittura. |
| 503 | `INTERNAL_ERROR` | L'esito della generazione o della memorizzazione del risultato salvato è incerto o temporaneamente non disponibile; usa il recupero autenticato del risultato prima di generare nuovamente. |
| 503 | `SERVER_RESTARTING` | Il server si sta riavviando. Riprova tra poco e mantieni lo stesso identificatore della richiesta per una modifica. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["transcription:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.