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

# OpenAI Spracherkennungs-API (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Transkribieren Sie Audio in Text, **vollständig kompatibel mit OpenAI's `/v1/audio/transcriptions`**. Jedes OpenAI SDK muss lediglich die `base_url` auf `https://api.acedata.cloud` setzen und den Schlüssel durch Ihr AceData Token ersetzen, um direkt verwendet zu werden. Unterstützt vollständige Antworten sowie die SSE-Inkrementaltranskription von `gpt-transcribe`.

* **Anforderungsadresse**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (Alias `POST /openai/audio/transcriptions`)
* **Authentifizierung**: Anfrage-Header `Authorization: Bearer {token}`
* **Anforderungsformat**: `multipart/form-data`
* **Abrechnung**: Abrechnung nach Audio-Dauer (siehe Tabelle unten), weniger als 1 Sekunde wird als 1 Sekunde berechnet.

## Anfrageparameter

| Feld | Typ | Erforderlich | Beschreibung |
| - | - | - | - |
| `file` | file | Ja | Zu transkribierende Audiodatei, maximal 25 MB. Unterstützt `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | string | Nein | `whisper-1` (Standard) oder `gpt-transcribe`, Unterschiede in den Fähigkeiten siehe Tabelle unten. |
| `language` | string | Nein | Audio-Sprache, ISO-639-1-Code (z. B. `zh`, `en`). Eingabe kann Genauigkeit und Geschwindigkeit erhöhen; leer lassen führt zur automatischen Erkennung. |
| `prompt` | string | Nein | Eingabeaufforderung zur Anleitung des Schreibstils oder zur Bereitstellung von Fachbegriffen zur Verbesserung der Erkennungsgenauigkeit. |
| `response_format` | string | Nein | `whisper-1`: `json` (Standard), `text`, `srt`, `verbose_json`, `vtt`; `gpt-transcribe`: nur `json`, `text`. |
| `temperature` | number | Nein | Abtasttemperatur 0–1, Standard 0. |
| `timestamp_granularities[]` | array | Nein | Zeitstempelgranularität, `word` oder `segment`, muss zusammen mit `response_format=verbose_json` verwendet werden. |
| `languages[]` | array | Nein | Kandidatensprachen (ISO-639-1), **nur `gpt-transcribe`**. Ausschließlich mit `language` inkompatibel, nicht gleichzeitig übergeben. |
| `keywords[]` | array | Nein | Fachbegriffe/Hinweise, **nur `gpt-transcribe`**, können die Erkennungsgenauigkeit von Markennamen und Personennamen erheblich verbessern. |
| `stream` | boolean | Nein | Bei `gpt-transcribe` auf `true` gesetzt, werden SSE-Inkrementalereignisse zurückgegeben; `whisper-1` ignoriert dieses Argument und gibt das vollständige Ergebnis zurück (entspricht dem Verhalten von OpenAI). |

## Welches Modell wählen

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Preis | \$0.0078 / Minute | **\$0.0059 / Minute** (günstiger) |
| Erkennungsgenauigkeit | Gut | **Besser**, insbesondere bei Markennamen und Fachbegriffen |
| Untertitel-Ausgabe (`srt`/`vtt`) | ✅ | ❌ |
| Wortzeitstempel | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Rückgabe der erkannten Sprache | Erfordert `verbose_json` | Standardrückgabe |
| SSE-Inkrementrückgabe | ❌ (wird ignoriert) | ✅ |

**Benötigen Sie Untertitel oder Wortzeitstempel → `whisper-1`; für alle anderen Szenarien wird `gpt-transcribe` empfohlen** (genauer und günstiger).

## Beispiel

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

Rückgabe:

```json theme={null}
{
  "text": "Ace Data Cloud Platform testet den Spracherkennungsendpunkt. Der schnelle braune Fuchs springt über den faulen Hund."
}
```

Chinesische Audios werden ebenfalls unterstützt, ohne die Sprache anzugeben:

```json theme={null}
{
  "text": "Willkommen auf der AceData Cloud Plattform, wir testen die Spracherkennungs-API, heute ist der 31. Juli."
}
```

### Untertitel generieren

Setzen Sie `response_format` auf `srt` oder `vtt`, um direkt eine verwendbare Untertiteldatei zu erhalten:

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

Rückgabeinhalt (`Content-Type: text/plain`):

```
1
00:00:00,000 --> 00:00:03,800
Ace Data Cloud Platform testet den Spracherkennungsendpunkt.

2
00:00:03,800 --> 00:00:06,280
Der schnelle braune Fuchs springt über den faulen Hund.
```

### Wortzeitstempel

Wenn die Start- und Endzeiten jedes Wortes benötigt werden, verwenden Sie `verbose_json` zusammen mit `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'
```

Rückgabe:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "Ace Data Cloud Platform testet den Spracherkennungsendpunkt. Der schnelle braune Fuchs springt über den faulen Hund.",
  "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
    }
  ]
}
```

### Stream-Transkription

`gpt-transcribe` kann durch `stream=true` `Content-Type: text/event-stream` zurückgeben. Der Dienst sendet OpenAI-kompatible Ereignisse unverändert:
`transcript.text.delta` enthält inkrementellen Text, `transcript.text.done` enthält den vollständigen Text und `usage` und zeigt einen normalen Abschluss an.

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

Ereignisstrombeispiel:

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

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

Der Empfang von `transcript.text.done` zeigt einen normalen Abschluss an. Wenn die Verarbeitung nach dem Aufbau des Streams fehlschlägt, wird die Verbindung nach dem Ereignis `event: error` beendet; ein aktives Trennen des Clients annulliert die Verarbeitung und es wird nicht im Hintergrund weiter generiert. `whisper-1` gibt auch bei Übertragung von `stream=true` weiterhin eine normale nicht-streamende Antwort zurück.

### Verwendung des offiziellen SDK

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

## Preise

| Modell | Preis auf dieser Plattform |
| - | - |
| `whisper-1` | \$0.0078 / Minute |
| `gpt-transcribe` | \$0.0059 / Minute |

> Abrechnung erfolgt nach der tatsächlichen Dauer des Audios, weniger als 1 Sekunde wird als 1 Sekunde berechnet, maximal 1 Stunde pro Einzelvorgang.

## Hinweise

* Einzelne Dateien maximal **25 MB**. Bei Überschreitung bitte zuerst aufteilen oder komprimieren (eine Senkung der Bitrate reicht normalerweise aus, die Spracherkennung hat keine hohen Anforderungen an die Audioqualität).
* `gpt-transcribe` unterstützt `stream=true` SSE; `whisper-1` ignoriert `stream` und gibt das vollständige Ergebnis zurück.
* Die Parameter sind mit den offiziellen OpenAI `/v1/audio/transcriptions` konsistent, das offizielle SDK muss nur die `base_url` ändern, um verwendet zu werden.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` gehören zu unseren noch nicht veröffentlichten Transkriptionsmodellen, die Übermittlung führt zu einem 400-Fehler anstelle einer stillen Ignorierung. Modell-spezifische Parameter (`timestamp_granularities[]` für `whisper-1`, `languages[]`/`keywords[]` für `gpt-transcribe`) führen ebenfalls zu einem 400-Fehler, wenn sie an nicht unterstützte Modelle übergeben werden.
* Anfragen können zeitaufwendig sein, es wird empfohlen, die Timeout-Einstellungen des Clients auf mindestens 300 Sekunden zu setzen.

## Fehlercodes

| Statuscode | code | Beschreibung |
| - | - | - |
| 400 | `bad_request` | `file` nicht bereitgestellt, Datei kann nicht analysiert werden oder Parameter sind ungültig (`model`/`response_format` nicht unterstützte Werte, `temperature` außerhalb von 0–1, `timestamp_granularities[]` nicht mit `verbose_json` kombiniert, Parameter übergeben, die von `whisper-1` nicht unterstützt werden). |
| 401 | `authentication_failed` | Token ungültig. |
| 403 | `used_up` | Unzureichendes Guthaben. |
| 413 | `request_too_large` | Audiodatei überschreitet das Limit von 25 MB. |
| 429 | `too_many_requests` | Anfragen sind zu häufig, bitte später erneut versuchen. |
| 500 | `api_error` | Interner Serverfehler, bitte später erneut versuchen. |


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