> ## 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 de reconnaissance vocale OpenAI (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Transcrire l'audio en texte, **entièrement compatible avec l'API `/v1/audio/transcriptions` d'OpenAI**. Il suffit de pointer `base_url` vers `https://api.acedata.cloud` et de remplacer la clé par votre AceData Token pour utiliser n'importe quel SDK OpenAI. Prend en charge les réponses complètes ainsi que la transcription incrémentale SSE de `gpt-transcribe`.

* **URL de la requête** : `POST https://api.acedata.cloud/v1/audio/transcriptions` (alias `POST /openai/audio/transcriptions`)
* **Authentification** : En-tête de requête `Authorization: Bearer {token}`
* **Format de la requête** : `multipart/form-data`
* **Facturation** : Facturation selon la durée de l'audio (voir tableau ci-dessous), moins de 1 seconde facturé comme 1 seconde.

## Paramètres de la requête

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `file` | fichier | Oui | Fichier audio à transcrire, maximum 25 Mo. Prend en charge `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | chaîne | Non | `whisper-1` (par défaut) ou `gpt-transcribe`, différences de capacité voir tableau ci-dessous. |
| `language` | chaîne | Non | Langue de l'audio, code ISO-639-1 (par exemple `zh`, `en`). Remplir peut améliorer la précision et la vitesse ; laisser vide pour une reconnaissance automatique. |
| `prompt` | chaîne | Non | Mot d'invite, utilisé pour guider le style d'écriture, ou fournir des noms propres, des termes pour améliorer la précision de la reconnaissance. |
| `response_format` | chaîne | Non | `whisper-1` : `json` (par défaut), `text`, `srt`, `verbose_json`, `vtt` ; `gpt-transcribe` : uniquement `json`, `text`. |
| `temperature` | nombre | Non | Température d'échantillonnage 0–1, par défaut 0. |
| `timestamp_granularities[]` | tableau | Non | Granularité des horodatages, `word` ou `segment`, doit être utilisé avec `response_format=verbose_json`. |
| `languages[]` | tableau | Non | Langues candidates (ISO-639-1), **uniquement `gpt-transcribe`**. Mutuellement exclusif avec `language`, ne pas transmettre simultanément. |
| `keywords[]` | tableau | Non | Indications de noms propres/termes, **uniquement `gpt-transcribe`**, peut considérablement améliorer la précision de la reconnaissance des noms de marque et des noms de personnes. |
| `stream` | booléen | Non | Lorsque `gpt-transcribe` est défini sur `true`, renvoie des événements incrémentaux SSE ; `whisper-1` ignorera ce paramètre et renverra le résultat complet (comportement conforme à celui d'OpenAI). |

## Quel modèle choisir

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Prix | 0,0078 \$ / minute | **0,0059 \$ / minute** (moins cher) |
| Précision de reconnaissance | Bonne | **Meilleure**, surtout pour les noms de marque et les noms propres |
| Sortie de sous-titres (`srt`/`vtt`) | ✅ | ❌ |
| Horodatages au niveau des mots | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Retour de la langue détectée | Nécessite `verbose_json` | Retour par défaut |
| Retour incrémental SSE | ❌ (le `stream` est ignoré) | ✅ |

**Besoin de sous-titres ou d'horodatages au niveau des mots → `whisper-1` ; pour les autres scénarios, recommandez `gpt-transcribe`** (plus précis et moins cher).

## Exemple

```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
```

Retour :

```json theme={null}
{
  "text": "La plateforme Ace Data Cloud teste le point de terminaison de reconnaissance vocale. Le rapide renard brun saute par-dessus le chien paresseux."
}
```

L'audio en chinois est également pris en charge, sans besoin de spécifier la langue :

```json theme={null}
{
  "text": "Bienvenue sur la plateforme AceData Cloud, nous testons l'interface de reconnaissance vocale, aujourd'hui c'est le 31 juillet."
}
```

### Générer des sous-titres

Définissez `response_format` sur `srt` ou `vtt` pour obtenir directement un fichier de sous-titres utilisable :

```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
```

Contenu retourné (`Content-Type: text/plain`) :

```
1
00:00:00,000 --> 00:00:03,800
La plateforme Ace Data Cloud teste le point de terminaison de reconnaissance vocale.

2
00:00:03,800 --> 00:00:06,280
Le rapide renard brun saute par-dessus le chien paresseux.
```

### Horodatages au niveau des mots

Pour obtenir le temps de début et de fin de chaque mot, utilisez `verbose_json` avec `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'
```

Retour :

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "La plateforme Ace Data Cloud teste le point de terminaison de reconnaissance vocale. Le rapide renard brun saute par-dessus le chien paresseux.",
  "words": [
    {
      "word": "La",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "plateforme",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Ace",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### Transcription en continu

`gpt-transcribe` peut renvoyer `Content-Type: text/event-stream` via `stream=true`. Le service enverra des événements compatibles avec OpenAI :
`transcript.text.delta` contient le texte incrémental, `transcript.text.done` contient le texte complet et `usage` et indique une fin 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
```

Exemple de flux d'événements :

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

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

La réception de `transcript.text.done` indique une fin normale. Si le traitement échoue après l'établissement du flux, la connexion se terminera après l'événement `event: error` ; une déconnexion active du client annulera le traitement en cours, sans continuer à générer en arrière-plan. `whisper-1`, même avec `stream=true`, renverra toujours une réponse normale non en continu.

### Utiliser le SDK officiel

```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)
```

## Prix

| Modèle | Prix sur cette plateforme |
| - | - |
| `whisper-1` | 0,0078 \$ / minute |
| `gpt-transcribe` | 0,0059 \$ / minute |

> Facturation selon la durée réelle de l'audio, toute durée inférieure à 1 seconde est facturée comme 1 seconde, la durée maximale par demande est plafonnée à 1 heure.

## Remarques

* Taille maximale d'un fichier **25 Mo**. Si cela dépasse, veuillez d'abord le diviser ou le compresser (réduire le débit binaire suffit généralement, la reconnaissance vocale n'exige pas une qualité sonore élevée).
* `gpt-transcribe` prend en charge `stream=true` SSE ; `whisper-1` ignorera `stream` et renverra le résultat complet.
* Les paramètres sont conformes à ceux de l'API officielle d'OpenAI `/v1/audio/transcriptions`, le SDK officiel nécessite simplement de modifier `base_url` pour être utilisé.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` appartiennent à des modèles de transcription que nous n'avons pas encore lancés, leur transmission renverra 400 au lieu d'être silencieusement ignorée. Les paramètres spécifiques au modèle (`timestamp_granularities[]` pour `whisper-1`, `languages[]`/`keywords[]` pour `gpt-transcribe`) renverront également 400 s'ils sont transmis à un modèle non pris en charge.
* Les requêtes peuvent prendre du temps, il est conseillé de définir un délai d'attente client d'au moins 300 secondes.

## Codes d'erreur

| Code d'état | code | Description |
| - | - | - |
| 400 | `bad_request` | `file` non fourni, fichier non analysable, ou paramètres illégaux (`model`/`response_format` valeurs non prises en charge, `temperature` hors de 0–1, `timestamp_granularities[]` non associé à `verbose_json`, paramètres non pris en charge pour `whisper-1` transmis). |
| 401 | `authentication_failed` | Token invalide. |
| 403 | `used_up` | Solde insuffisant. |
| 413 | `request_too_large` | Fichier audio dépassant la limite de 25 Mo. |
| 429 | `too_many_requests` | Trop de requêtes, veuillez réessayer plus tard. |
| 500 | `api_error` | Erreur interne du service, veuillez réessayer plus tard. |


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