> ## 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. # Trascrivi contenuti multimediali > Trascrivi un file audio o video caricato in testo semplice, paragrafi e frasi. Si applicano gli stessi limiti del piano e la stessa quota giornaliera dello strumento web. Restituisce un riferimento compatto al risultato salvato; usa il relativo getAction o downloadAction per recuperare l'output completo. Trascrivi un file audio o video caricato in testo semplice, paragrafi e frasi. Si applicano gli stessi limiti del piano e la stessa quota giornaliera dello strumento web. 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/transcription_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 Un fileKey di proprietà dell'utente restituito da un caricamento completato o da un'importazione multimediale. Ogni generazione consuma il file sorgente caricato. Lunghezza minima: 1. Lunghezza massima: 1024. Valore testuale. Lunghezza minima: 1. Lunghezza massima: 255. Pattern: `^[^/\\\r\n\0]+$`. Elenco di valori. Consulta lo schema di input completo per la struttura degli elementi. Numero massimo di elementi: 100. 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": { "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "An owned fileKey returned by a completed upload or media import. Each generation consumes its uploaded source." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\\\r\\n\\0]+$" }, "keyterms": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "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": ["fileKey"], "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/transcription_create' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"fileKey":"uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4","fileName":"interview.mp4","keyterms":["VoiceCheap"],"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}' ``` ```javascript JavaScript theme={null} const input = { fileKey: 'uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4', fileName: 'interview.mp4', keyterms: ['VoiceCheap'], requestId: '13579bdf-2468-4ace-8bdf-0123456789ab', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/transcription_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/transcription_create", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.mp4", "fileName": "interview.mp4", "keyterms": ["VoiceCheap"], "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 a un risultato di trascrizione salvato. Il relativo JSON completo contiene transcript.raw, transcript.paragraphs, transcript.sentences e, facoltativamente, transcript.detectedLanguage. ```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": "transcription_create", "createdAt": 1792152000000, "fileName": "voicecheap-transcription_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json", "byteLength": 116, "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": "transcription_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": "transcription_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":"transcription_create"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "transcription_create", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b", "operation": "transcription_create", "createdAt": 1792152000000, "fileName": "voicecheap-transcription_create-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json", "byteLength": 116, "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 fileKey di un caricamento o di un'importazione completati e di tua proprietà e consideralo monouso. Una volta iniziata l'elaborazione multimediale, la pulizia elimina il file di origine dopo il completamento o un errore di elaborazione. Un rifiuto dovuto alla validazione o alla quota prima dell'elaborazione può lasciarlo intatto. Riutilizza requestId originale per recuperare la generazione accettata prima di avviarne un'altra. * Accetta audio o video supportati fino a 200 MiB e 2 ore. fileName è un metadato di visualizzazione facoltativo; la proprietà e la convalida multimediale continuano a usare fileKey. * Quota giornaliera per strumento: Beginner 5, Starter 15, Creator 30, Pro 60, Scale 100 ed Enterprise 100 generazioni riuscite. È condivisa con lo strumento web corrispondente e usa la finestra di azzeramento dello strumento dell'account. * Viene salvata una voce nella cronologia personale delle trascrizioni senza garanzia di riuscita. Il risultato durevole dell'integrazione rimane il percorso di recupero dell'output completo anche se non è stata salvata alcuna voce nella cronologia dello strumento. ## 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 contenuto multimediale supera il limite di durata dell'operazione. | | 400 | `DURATION_UNKNOWN` | La fase di esecuzione non è riuscita a determinare una durata positiva del contenuto multimediale. | | 400 | `FILE_TOO_LARGE` | La sorgente memorizzata supera il limite di byte specifico dell'operazione. | | 400 | `IDEMPOTENCY_CONFLICT` | Gli ID della richiesta nell'header e nel corpo sono diversi. | | 400 | `INVALID_FILE_TYPE` | L'estensione del nome file non è supportata per questa operazione. | | 400 | `INVALID_MEDIA_DURATION` | La durata rilevata del file sorgente è assente, non valida oppure supera il limite di durata del piano. | | 400 | `INVALID_MEDIA_STREAM` | La sorgente non contiene un flusso audio utilizzabile per la trascrizione. | | 400 | `INVALID_REQUEST_ID` | requestId o Idempotency-Key non è un UUID v4. | | 400 | `VALIDATION_ERROR` | Gli argomenti non soddisfano lo schema dell'azione oppure è stato fornito un argomento sconosciuto. | | 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 | `INVALID_FILE_REFERENCE` | fileKey non è un riferimento valido a un caricamento completato appartenente all'attore. | | 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. | | 404 | `MEDIA_NOT_FOUND` | Il caricamento completato del file sorgente è assente o vuoto; una generazione precedente potrebbe averlo consumato. | | 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. | | 422 | `TRANSCRIPTION_EMPTY` | L'audio è silenzioso oppure non è stato rilevato alcun dialogo parlato. | | 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 | `TRANSCRIPTION_TOOL_DAILY_LIMIT_REACHED` | L'attore ha esaurito la quota giornaliera dello strumento di trascrizione. | | 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. | | 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.