> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API di riconoscimento vocale OpenAI (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Trascrivi audio in testo, **completamente compatibile con OpenAI `/v1/audio/transcriptions`**. Qualsiasi SDK OpenAI deve semplicemente puntare `base_url` a `https://api.acedata.cloud` e sostituire la chiave con il tuo AceData Token per essere utilizzato direttamente. Supporta risposte complete e anche la trascrizione incrementale SSE di `gpt-transcribe`.

* **URL della richiesta**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (alias `POST /openai/audio/transcriptions`)
* **Autenticazione**: intestazione della richiesta `Authorization: Bearer {token}`
* **Formato della richiesta**: `multipart/form-data`
* **Fatturazione**: fatturato in base alla durata dell'audio (vedi tabella sottostante), meno di 1 secondo fatturato come 1 secondo.

## Parametri della richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `file` | file | Sì | File audio da trascrivere, massimo 25 MB. Supporta `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | string | No | `whisper-1` (predefinito) o `gpt-transcribe`, differenze di capacità vedono la tabella sottostante. |
| `language` | string | No | Lingua dell'audio, codice ISO-639-1 (es. `zh`, `en`). Compilarlo può migliorare accuratezza e velocità; lasciarlo vuoto per riconoscimento automatico. |
| `prompt` | string | No | Parola chiave per guidare lo stile di scrittura o fornire nomi propri, termini per migliorare l'accuratezza del riconoscimento. |
| `response_format` | string | No | `whisper-1`: `json` (predefinito), `text`, `srt`, `verbose_json`, `vtt`; `gpt-transcribe`: solo `json`, `text`. |
| `temperature` | number | No | Temperatura di campionamento 0–1, predefinita 0. |
| `timestamp_granularities[]` | array | No | Granularità del timestamp, `word` o `segment`, deve essere utilizzato con `response_format=verbose_json`. |
| `languages[]` | array | No | Lingue candidate (ISO-639-1), **solo `gpt-transcribe`**. Incompatibile con `language`, non inviare entrambi. |
| `keywords[]` | array | No | Suggerimenti per nomi propri/termini, **solo `gpt-transcribe`**, può migliorare significativamente l'accuratezza del riconoscimento di nomi di marchi e persone. |
| `stream` | boolean | No | Se `gpt-transcribe` è impostato su `true`, restituisce eventi incrementali SSE; `whisper-1` ignorerà questo parametro e restituirà risultati completi (comportamento coerente con quello ufficiale di OpenAI). |

## Quale modello scegliere

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Prezzo | \$0.0078 / minuto | **\$0.0059 / minuto** (più economico) |
| Accuratezza del riconoscimento | Buona | **Migliore**, soprattutto per nomi di marchi e nomi propri |
| Uscita sottotitoli (`srt`/`vtt`) | ✅ | ❌ |
| Timestamp a livello di parola | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Restituisce lingua rilevata | Necessita `verbose_json` | Restituisce per default |
| Restituzione incrementale SSE | ❌ (ignora `stream`) | ✅ |

**Hai bisogno di sottotitoli o timestamp a livello di parola → `whisper-1`; per altri scenari si consiglia `gpt-transcribe`** (più preciso e più economico).

## Esempio

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1
```

Risposta:

```json theme={null}
{
  "text": "Ace Data Cloud Platform is testing the speech recognition endpoint. The quick brown fox jumps over the lazy dog."
}
```

L'audio in cinese è supportato senza dover specificare la lingua:

```json theme={null}
{
  "text": "欢迎使用 AceData Cloud 平台,我们正在测试语音识别接口,今天是 7 月 31 号。"
}
```

### Generazione di sottotitoli

Imposta `response_format` su `srt` o `vtt` per ottenere direttamente un file di sottotitoli utilizzabile:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=srt \
  -o subtitle.srt
```

Contenuto restituito (`Content-Type: text/plain`):

```
1
00:00:00,000 --> 00:00:03,800
Ace Data Cloud Platform is testing the speech recognition endpoint.

2
00:00:03,800 --> 00:00:06,280
The quick brown fox jumps over the lazy dog.
```

### Timestamp a livello di parola

Se hai bisogno dei tempi di inizio e fine di ogni parola, utilizza `verbose_json` insieme a `timestamp_granularities[]=word`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=verbose_json \
  -F 'timestamp_granularities[]=word'
```

Risposta:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "Ace Data Cloud Platform is testing the speech recognition endpoint. The quick brown fox jumps over the lazy dog.",
  "words": [
    {
      "word": "Ace",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "Data",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Cloud",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### Trascrizione in streaming

`gpt-transcribe` può restituire `Content-Type: text/event-stream` tramite `stream=true`. Il servizio invierà eventi compatibili con OpenAI:
`transcript.text.delta` porta il testo incrementale, `transcript.text.done` porta il testo completo e `usage` e indica il completamento normale.

```shell theme={null}
curl -N -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=gpt-transcribe \
  -F stream=true
```

Esempio di flusso di eventi:

```text theme={null}
data: {"type":"transcript.text.delta","delta":"Hello"}

data: {"type":"transcript.text.done","text":"Hello world","usage":{"type":"tokens","input_tokens":14,"output_tokens":3,"total_tokens":17}}
```

Ricevere `transcript.text.done` indica che il completamento è avvenuto correttamente. Se si verifica un errore dopo l'instaurazione del flusso, la connessione terminerà dopo l'evento `event: error`; se il client si disconnette attivamente, il processo verrà annullato e non continuerà a generare in background. `whisper-1`, anche se si passa `stream=true`, restituirà comunque una risposta normale non in streaming.

### Utilizzo dell'SDK ufficiale

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)
print(result.text)
```

## Prezzi

| Modello | Prezzo sulla piattaforma |
| - | - |
| `whisper-1` | \$0.0078 / minuto |
| `gpt-transcribe` | \$0.0059 / minuto |

> La fatturazione è basata sulla durata effettiva dell'audio, con un minimo di 1 secondo per durate inferiori a 1 secondo, e un massimo di 1 ora per singola richiesta.

## Note

* La dimensione massima di un singolo file è **25 MB**. Se supera, si prega di suddividere o comprimere (ridurre il bitrate di solito è sufficiente, il riconoscimento vocale non richiede alta qualità audio).
* `gpt-transcribe` supporta `stream=true` SSE; `whisper-1` ignorerà `stream` e restituirà il risultato completo.
* I parametri sono coerenti con l'API ufficiale di OpenAI `/v1/audio/transcriptions`, l'SDK ufficiale richiede solo di modificare `base_url` per essere utilizzato.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` appartengono a modelli di trascrizione non ancora disponibili, l'invio restituirà 400 invece di essere silenziosamente ignorato. I parametri specifici del modello (`timestamp_granularities[]` per `whisper-1`, `languages[]`/`keywords[]` per `gpt-transcribe`) restituiranno anch'essi 400 se inviati a modelli non supportati.
* Le richieste possono richiedere tempo, si consiglia di impostare un timeout del client non inferiore a 300 secondi.

## Codici di errore

| Stato | codice | Descrizione |
| - | - | - |
| 400 | `bad_request` | `file` non fornito, file non può essere elaborato, o parametri non validi (`model`/`response_format` valori non supportati, `temperature` oltre 0–1, `timestamp_granularities[]` non abbinato a `verbose_json`, parametri non supportati per `whisper-1`). |
| 401 | `authentication_failed` | token non valido. |
| 403 | `used_up` | Saldo insufficiente. |
| 413 | `request_too_large` | Il file audio supera il limite di 25 MB. |
| 429 | `too_many_requests` | Richieste troppo frequenti, si prega di riprovare più tardi. |
| 500 | `api_error` | Errore interno del servizio, si prega di riprovare più tardi. |


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