> ## 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. # Esporta un risultato salvato delle azioni sui sottotitoli > Esporta il risultato completo di tua proprietà come testo JSON con nome file e tipo di contenuto. L'accesso resta autenticato; nessun URL multimediale pubblico espone la trascrizione. Esporta il risultato completo di tua proprietà come testo JSON con nome file e tipo di contenuto. L'accesso resta autenticato; nessun URL multimediale pubblico espone la trascrizione. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/subtitles_result_download ``` ## 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: `subtitles:read`. È 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. Formato: "uuid". Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$`. 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": { "resultId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["resultId"], "additionalProperties": false } ``` ## 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/subtitles_result_download' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"resultId":"b3caf96f-5f2a-4619-832c-a12c0d57f78b"}' ``` ```javascript JavaScript theme={null} const input = { resultId: 'b3caf96f-5f2a-4619-832c-a12c0d57f78b', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/subtitles_result_download', { 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/subtitles_result_download", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b"}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## Risposta Una prima esecuzione riuscita restituisce HTTP 200 con il risultato dell'operazione in data. Una ripetizione può invece restituire lo stato della richiesta salvata. L'esempio mostra una risposta supportata, non tutti i campi facoltativi. Metadati di output salvati con il JSON generato completo serializzato come stringa content per un'esportazione locale autenticata. ```json HTTP 200 theme={null} { "data": { "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b", "operation": "captions_transcribe", "createdAt": 1792152000000, "fileName": "voicecheap-captions_transcribe-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json", "byteLength": 190, "contentType": "application/json; charset=utf-8", "status": "completed", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "getAction": "subtitles_result_get", "downloadAction": "subtitles_result_download", "listAction": "subtitles_result_list", "content": "{\"words\":[{\"text\":\"Hello\",\"startMs\":0,\"endMs\":500,\"speakerId\":\"speaker_0\"},{\"text\":\"world.\",\"startMs\":500,\"endMs\":1500,\"speakerId\":\"speaker_0\"}],\"detectedLanguage\":\"en\",\"durationSeconds\":60}" } } ``` ## 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. | | `data.content` | Risultato pubblico originale completo della generazione codificato come testo JSON, pronto per essere salvato in fileName. | ## 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. * resultId è un UUID proveniente da un riferimento di generazione completata o da result\_list di questo dominio. È diverso dal requestId dell'azione e dall'historyId dello strumento web. * I risultati appartengono all'attore autenticato e al dominio di autorizzazione. Un risultato del dominio subtitles non può essere letto tramite le azioni transcription, né viceversa. * Il JSON completo salvato viene crittografato a riposo e conservato indipendentemente dalla cache limitata di interrogazione delle azioni. Il recupero richiede comunque l'autenticazione; non viene emesso alcun URL pubblico del JSON della trascrizione o dei sottotitoli. * Queste azioni recuperano output esistenti e non generano contenuti multimediali né usano una quota giornaliera. Ogni recupero riuscito usa comunque una chiamata di integrazione mensile. * I metadati con stato pending indicano che il salvataggio dell'output richiede un recupero. La lettura o il download del contenuto tenta di recuperare un oggetto crittografato già salvato; controllalo prima di avviare un'altra generazione. * Scrivi content in fileName usando UTF-8 oppure usa JSON.parse(content) per recuperare l'output strutturato. La risposta esterna non contiene una proprietà result né un URL di download multimediale. * byteLength descrive il JSON UTF-8 contenuto in content; contentType è application/json; charset=utf-8. Il download tenta anche il recupero dell'output crittografato in attesa. ## 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 | `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 | `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. | | 404 | `TOOL_RESULT_NOT_FOUND` | Il risultato è assente, appartiene a un altro utente chiamante oppure appartiene all'altro dominio di autorizzazioni. | | 410 | `TOOL_RESULT_ACCOUNT_UNAVAILABLE` | L'account chiamante è in fase di eliminazione oppure non esiste più durante il recupero. | | 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. | | 500 | `INTERNAL_ERROR` | Non è stato possibile leggere o convalidare il JSON completato salvato. | | 503 | `INTERNAL_ERROR` | Un risultato salvato con stato pending non può ancora essere recuperato; controlla lo stesso risultato prima di rigenerarlo. | | 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": ["subtitles:read"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.