> ## 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 è organizzata secondo i principi REST. Utilizza metodi HTTP standard, restituisce risposte codificate in JSON e utilizza codici di risposta HTTP standard.

## URL di base

Tutte le richieste API devono essere effettuate a:

```
https://api.voicecheap.ai
```

## Autenticazione

Tutte le richieste richiedono una chiave API passata nell'intestazione `x-api-key`. Vedi la pagina [Autenticazione](/docs/it/authentication) per i dettagli.

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

## Endpoint disponibili

<CardGroup cols={2}>
  <Card title="Trascrivi media" icon="captions" href="/docs/it/api-reference/transcribe">
    `POST /v1/transcribe`

    Trascrivi un file caricato come JSON, SRT o VTT.
  </Card>

  <Card title="Esporta trascrizione progetto" icon="file-lines" href="/docs/it/api-reference/project-transcript">
    `POST /v1/projects/{projectId}/transcript`

    Recupera le trascrizioni originali o tradotte del progetto.
  </Card>

  <Card title="Avvia traduzione" icon="play" href="/docs/it/api-reference/translate">
    `POST /v1/translate`

    Carica un file video o audio e avvia un progetto di traduzione.
  </Card>

  <Card title="Ottieni stato traduzione" icon="magnifying-glass" href="/docs/it/api-reference/translation-status">
    `GET /v1/translate/{projectId}/status`

    Controlla lo stato di un progetto di traduzione e recupera i risultati.
  </Card>

  <Card title="Ottieni dettagli progetto" icon="list-tree" href="/docs/it/api-reference/project-details">
    `GET /v1/projects/{projectId}`

    Recupera la cronologia delle versioni tradotte, la cronologia della sincronizzazione labiale e lo stato del progetto.
  </Card>

  <Card title="Elimina progetto" icon="trash" href="/docs/it/api-reference/delete-project">
    `DELETE /v1/translate/{projectId}`

    Elimina definitivamente un progetto di traduzione e le sue risorse.
  </Card>
</CardGroup>

## Flusso di lavoro di traduzione

Il flusso di lavoro tipico per tradurre un video è:

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

    Client->>API: POST /v1/translate (file + options)
    API->>Processing: Queue translation job
    API-->>Client: 200 OK (projectId)

    loop Poll for status
        Client->>API: GET /v1/translate/{projectId}/status
        API-->>Client: Status (processing/success/failed)
    end

    Note over Client: Download translated video URL when status is "success"
```

## Formato di risposta

Tutte le risposte riuscite seguono questa struttura generale:

```json theme={null}
{
  "success": true,
  "message": "Description of the result"
  // Additional fields specific to the endpoint
}
```

Le risposte di errore seguono questa struttura:

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}
```

## Codici di stato HTTP

| Codice di stato | Descrizione                                        |
| --------------- | -------------------------------------------------- |
| 200             | Successo                                           |
| 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                |
| 429             | Troppe richieste - Limite di frequenza superato    |
| 500             | Errore interno del server                          |