> ## 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. # Ottieni il ciclo di utilizzo di un progetto > Ottieni addebiti di minuti, rimborsi ed eventi del ciclo di vita di traduzione e sincronizzazione labiale per un progetto nella tua area di lavoro. Ottieni addebiti di minuti, rimborsi ed eventi del ciclo di vita di traduzione e sincronizzazione labiale per un progetto nella tua area di lavoro. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/usage_project_get ``` ## 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: `usage: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. Lunghezza minima: 1. Lunghezza massima: 200. Pattern: `^[^/]+$`. 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": { "projectId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/]+$" } }, "required": ["projectId"], "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/usage_project_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"projectId":"project_123"}' ``` ```javascript JavaScript theme={null} const input = { projectId: 'project_123', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_project_get', { 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/usage_project_get", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"projectId": "project_123"}, 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. Restituisce i totali in minuti dell'intero progetto e gli eventi del ciclo di vita delle sue esecuzioni di traduzione nell'area di lavoro attiva. ```json HTTP 200 theme={null} { "data": { "kind": "project", "isHistoricalDerived": false, "summary": { "title": "Product launch", "sourceLanguage": "English", "totals": { "translationBaseMinutes": 2, "lipSyncExtraMinutes": 0, "lipSyncProExtraMinutes": 0, "lipSyncPro2ExtraMinutes": 0, "totalChargedMinutes": 2, "refundedMinutes": 0, "netUsedMinutes": 2 } }, "events": [ { "id": "project_123-project-created", "type": "project_created", "timestamp": 1792065540000, "tone": "neutral" }, { "id": "version_123-translation-launched", "type": "translation_launched", "timestamp": 1792065600000, "tone": "neutral", "minuteDelta": 2, "relatedRunLabel": "French" }, { "id": "version_123-translation-completed", "type": "translation_completed", "timestamp": 1792065720000, "tone": "success", "isDerived": false, "relatedRunLabel": "French" } ] } } ``` ## Campi del risultato | Campo | Descrizione | | - | - | | `data.kind` | translation o project. | | `data.isHistoricalDerived` | Indica se uno o più dettagli di utilizzo sono stati ricavati da dati storici. | | `data.summary.title` | Nome visualizzato del progetto. | | `data.summary.sourceLanguage` | Etichetta formattata della lingua sorgente, quando disponibile. | | `data.summary.targetLanguage` | Lingua di destinazione per un ciclo di vita della traduzione; omessa da un ciclo di vita del progetto. | | `data.summary.translationStatus` | Stato della traduzione per un ciclo di vita della traduzione; omesso dal ciclo di vita di un progetto. | | `data.summary.lipSyncStatus` | Stato della sincronizzazione labiale nel ciclo di vita di una traduzione; omesso dal ciclo di vita di un progetto. | | `data.summary.totals.translationBaseMinutes` | Minuti di traduzione di base addebitati per le righe corrispondenti. | | `data.summary.totals.lipSyncExtraMinutes` | Minuti aggiuntivi di sincronizzazione labiale Standard addebitati. | | `data.summary.totals.lipSyncProExtraMinutes` | Minuti aggiuntivi di lip-sync Pro addebitati. | | `data.summary.totals.lipSyncPro2ExtraMinutes` | Minuti aggiuntivi addebitati per la sincronizzazione labiale Pro 2. | | `data.summary.totals.totalChargedMinutes` | Minuti totali addebitati prima dei rimborsi. | | `data.summary.totals.refundedMinutes` | Minuti rimborsati. | | `data.summary.totals.netUsedMinutes` | Minuti addebitati meno minuti rimborsati. | | `data.events` | Eventi del ciclo di vita in ordine di timestamp; gli eventi senza timestamp seguono quelli con timestamp. | | `data.events[].id` | Identificatore stabile dell'evento per la fase del ciclo di vita segnalata. | | `data.events[].type` | Tipo di evento, ad esempio project\_created, translation\_launched, translation\_completed o lip\_sync\_refunded. | | `data.events[].timestamp` | Timestamp facoltativo dell'evento in millisecondi. | | `data.events[].tone` | neutral, success, warning o danger. | | `data.events[].relatedRunLabel` | Etichetta facoltativa della lingua di destinazione e dell'esecuzione per gli eventi del ciclo di vita del progetto. | | `data.events[].minuteDelta` | Minuti addebitati facoltativi come numero positivo o minuti rimborsati come numero negativo. | | `data.events[].isDerived` | Flag facoltativo che indica un evento ricostruito da dati storici. | ## Note sull'operazione * Il progetto deve avere almeno una riga di utilizzo nell'area di lavoro attiva; un progetto senza righe di utilizzo restituisce un errore. * Il riepilogo riguarda l'intero progetto e omette i singoli valori targetLanguage, translationStatus e lipSyncStatus. I singoli eventi includono un'etichetta della lingua di destinazione o dell'esecuzione, se applicabile. * Gli eventi omettono i messaggi grezzi degli errori di elaborazione e le etichette di visualizzazione degli eventi. ## 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 | `BAD_REQUEST` | Il progetto non è stato trovato oppure non ha righe di utilizzo delle traduzioni nell'area di lavoro attiva. | | 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` | L'oggetto JSON contiene un campo non supportato, un valore non valido o un argomento obbligatorio mancante. | | 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` | Concedi tutte le autorizzazioni richieste o scegli un'altra credenziale. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Impossibile verificare i limiti di integrazione dell'account. | | 403 | `SUBSCRIPTION_REQUIRED` | Usa un abbonamento a pagamento attivo. | | 403 | `TEAM_MEMBERSHIP_INVALID` | L'appartenenza attuale dell'account al team non corrisponde all'area di lavoro di questa connessione. Aggiorna l'appartenenza e riconnettiti. | | 403 | `TEAM_OWNER_NOT_FOUND` | Non è stato possibile trovare l'account effettivo del proprietario del team. | | 404 | `ACCOUNT_NOT_FOUND` | Non è stato possibile trovare l'account o l'account dell'area di lavoro attiva. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Attendi il ripristino mensile o cambia piano. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Rispetta Retry-After quando presente e applica attese crescenti tra i tentativi. | | 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. | | 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": ["usage:read"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.