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

# Riferimento API

> Riferimento completo per l'API REST VoiceCheap

# Riferimento API

L’API VoiceCheap usa metodi e codici di stato HTTP standard. La maggior parte degli endpoint restituisce JSON; le esportazioni delle trascrizioni possono restituire anche SRT o VTT.

Per le impostazioni dell'account, la gestione del team, gli strumenti multimediali e altri flussi di lavoro, usa il [catalogo delle azioni](https://api-docs.voicecheap.ai/docs/it/api-reference/actions.md). Questi flussi sono disponibili anche tramite il [server MCP dell'account](https://api-docs.voicecheap.ai/docs/it/ai/model-context-protocol.md), tranne la creazione e la rotazione del segreto di firma dei webhook, che richiedono REST. Gestisci le credenziali in [Integrazioni](https://api-docs.voicecheap.ai/docs/it/ai/integrations.md) e consulta i [limiti di utilizzo](https://api-docs.voicecheap.ai/docs/it/api-reference/limits.md).

## URL di base

Tutte le richieste API devono essere effettuate a:

```text theme={null}
https://api.voicecheap.ai
```

## Autenticazione

Autentica le chiamate REST private con una chiave API in `x-api-key` o `Authorization: Bearer`. Il documento OpenAPI è pubblico. Consulta [Autenticazione](https://api-docs.voicecheap.ai/docs/it/authentication.md) per le credenziali con autorizzazioni specifiche e OAuth per MCP.

## API di azioni JSON

Le sezioni account, team, progetti, voci e strumenti multimediali documentano ogni azione JSON separatamente. Tutte queste route usano `POST`, anche per leggere ed eliminare; invia gli argomenti nel corpo JSON. Le route per il caricamento di file e i progetti esistenti riportate sotto mantengono i propri metodi HTTP.

Crea una chiave API con `account:read`, imposta la variabile d’ambiente `VOICECHEAP_API_KEY` e prova questa richiesta di sola lettura:

```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/account_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

Un’azione completata restituisce HTTP 200 con il risultato in `data`. Un’azione lunga restituisce HTTP 202 e un `requestId`; consulta lo [stato della richiesta](https://api-docs.voicecheap.ai/docs/it/api-reference/actions/requests/action-request-get.md) per recuperare il risultato. Un processo multimediale può continuare dopo il completamento della richiesta di azione.

Consulta [tutte le azioni per area](https://api-docs.voicecheap.ai/docs/it/api-reference/actions.md) oppure [scopri le azioni e gli schemi consentiti per la tua chiave](https://api-docs.voicecheap.ai/docs/it/api-reference/discovery/actions-list.md). Ogni pagina indica autorizzazioni, parametri, esempi ed errori.

## Tipi di contenuto

* **Richiesta**: Usa `multipart/form-data` per i caricamenti di file, `application/json` per altre richieste
* **Risposta**: Gli endpoint JSON restituiscono `application/json`. Le esportazioni di trascrizioni possono anche restituire testo SRT o VTT.

## Caricamento di file e route dei progetti esistenti

> [card] [Trascrivi media](https://api-docs.voicecheap.ai/docs/it/api-reference/transcribe.md)
>
> `POST /v1/transcribe`
>
> Trascrivi un file caricato come JSON, SRT o VTT.

> [card] [Esporta trascrizione progetto](https://api-docs.voicecheap.ai/docs/it/api-reference/project-transcript.md)
>
> `POST /v1/projects/{projectId}/transcript`
>
> Recupera le trascrizioni originali o tradotte del progetto.

> [card] [Crea progetto](https://api-docs.voicecheap.ai/docs/it/api-reference/create-project.md)
>
> `POST /v1/projects`
>
> Carica un file video o audio e avvia solo la trascrizione.

> [card] [Avvia traduzione](https://api-docs.voicecheap.ai/docs/it/api-reference/translate.md)
>
> `POST /v1/translate`
>
> Carica un file video o audio e avvia un progetto di traduzione.

> [card] [Doppia progetto](https://api-docs.voicecheap.ai/docs/it/api-reference/dub-project.md)
>
> `POST /v1/projects/{projectId}/dub`
>
> Doppia un progetto trascritto usando il tuo file SRT tradotto.

> [card] [Ottieni stato traduzione](https://api-docs.voicecheap.ai/docs/it/api-reference/translation-status.md)
>
> `GET /v1/translate/{projectId}/status`
>
> Controlla lo stato di un progetto di traduzione e recupera i risultati.

> [card] [Ottieni dettagli progetto](https://api-docs.voicecheap.ai/docs/it/api-reference/project-details.md)
>
> `GET /v1/projects/{projectId}`
>
> Recupera la cronologia delle versioni tradotte, la cronologia della sincronizzazione labiale e lo stato del progetto.

> [card] [Elimina progetto](https://api-docs.voicecheap.ai/docs/it/api-reference/delete-project.md)
>
> `DELETE /v1/translate/{projectId}`
>
> Elimina definitivamente un progetto di traduzione e le sue risorse.

## Flusso di lavoro di traduzione

Il flusso di lavoro tipico per tradurre un video è:

```mermaid theme={null}
sequenceDiagram
    participant Client as Client
    participant API
    participant Processing as Elaborazione

    Client->>API: POST /v1/translate (file + opzioni)
    API->>Processing: Accoda il lavoro di traduzione
    API-->>Client: 201 (projectId)

    loop Controlla lo stato
        Client->>API: GET /v1/translate/{projectId}/status
        API-->>Client: status (processing/success/failed)
    end

    Note over Client: Scarica l’URL del video tradotto quando lo stato è "success"
```

## Formato di risposta

Le route esistenti per file e progetti riportate sotto mantengono i rispettivi formati di risposta.

I campi delle risposte riuscite dipendono dall’endpoint. La creazione di un progetto e l’avvio del doppiaggio restituiscono `success`, `message` e `projectId`. Le richieste di stato e dettagli restituiscono lo stato del progetto; quelle di trascrizione restituiscono JSON, SRT o VTT. Consulta la pagina di ciascun endpoint per i campi esatti.

Gli errori restituiscono un oggetto JSON con `code` e `message`, talvolta anche con `details`. Consulta i [codici di errore](https://api-docs.voicecheap.ai/docs/it/api-reference/errors.md).

## Codici di stato HTTP

| Codice di stato | Descrizione |
| - | - |
| 200 | Successo |
| 201 | Creato – È stato avviato un progetto o un doppiaggio |
| 202 | Accettato - Segui l’azione asincrona con il relativo identificatore di richiesta |
| 400 | Richiesta errata - Parametri non validi |
| 401 | Non autorizzato - Chiave API non valida o mancante |
| 403 | Vietato - Permessi o crediti insufficienti |
| 404 | Non trovato - La risorsa non esiste |
| 409 | Conflitto – Lo stato del progetto non consente la richiesta |
| 413 | File troppo grande – Il file caricato supera il limite |
| 429 | Troppe richieste - Limite di frequenza superato |
| 500 | Errore interno del server |
| 502 | Errore di elaborazione – La trascrizione non è stata completata |
| 503 | Servizio temporaneamente non disponibile - Mantieni lo stesso identificatore e verifica lo stato prima di riprovare |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.