API-Dokumentation

Die Swisscribe-API ist kompatibel mit der OpenAI-API. Die offiziellen SDKs für Python und Node funktionieren unverändert: Sie setzen nur die Basis-URL und Ihren Schlüssel. Aufnahmen werden in der Schweiz verarbeitet und gespeichert.

Schnellstart

1. Konto erstellen (mit CHF 1.00 Startguthaben).
2. Im Dashboard unter API-Schlüssel einen Schlüssel erstellen.
3. Basis-URL https://swisscribe.ch/v1 verwenden:

from openai import OpenAI

client = OpenAI(
    base_url="https://swisscribe.ch/v1",
    api_key="sk-swc-...",
)

with open("interview.mp3", "rb") as f:
    srt = client.audio.transcriptions.create(
        model="swisscribe-pro",
        file=f,
        response_format="srt",
        # lange Dateien: bis 30 Minuten warten
        timeout=1800,
    )
print(srt)

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage im Header Authorization: Bearer sk-swc-…. Wir zeigen den Schlüssel nur einmal an und speichern ihn nicht im Klartext. Behandeln Sie ihn wie ein Passwort: Er gehört nicht in Browser-Code oder öffentliche Repositories, sondern in eine Umgebungsvariable. Einen verlorenen Schlüssel widerrufen Sie im Dashboard; er funktioniert dann sofort nicht mehr.

Transkription erstellen

POST https://swisscribe.ch/v1/audio/transcriptions als multipart/form-data. Die Anfrage wartet, bis das Transkript fertig ist, und gibt es im gewünschten Format zurück. Jede Transkription erscheint ausserdem in Ihrem Dashboard und kann dort 7 Tage lang als ZIP heruntergeladen werden, auch wenn die Verbindung abbricht.

Parameter

Modelle

GET https://swisscribe.ch/v1/models listet beide Modelle.

Antwortformate

Ein Segment entspricht einem Satz. Beispiel für verbose_json mit timestamp_granularities[]=word:

{
  "task": "transcribe",
  "language": "german",
  "duration": 95.2,
  "text": "Guten Tag zusammen, wir fangen gleich an. …",
  "segments": [
    {
      "id": 0, "seek": 0, "start": 3.02, "end": 5.61,
      "text": "Guten Tag zusammen, wir fangen gleich an.",
      "tokens": [], "temperature": 0, "avg_logprob": 0,
      "compression_ratio": 0, "no_speech_prob": 0
    }
  ],
  "words": [{ "word": "Guten", "start": 3.02, "end": 3.31 }],
  "usage": { "type": "duration", "seconds": 96 }
}

Abrechnung

API-Aufträge kosten gleich viel wie Uploads im Web. Abgerechnet wird pro Sekunde Audio, pro Datei auf den nächsten Rappen aufgerundet. Der Betrag wird beim Start vom Guthaben abgezogen. Schlägt die Verarbeitung fehl, schreiben wir ihn automatisch wieder gut.

Fehler

Fehler haben das Format der OpenAI-API:

{
  "error": {
    "message": "Ihr Guthaben reicht für diese Datei nicht.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

Bei 400, 401, 402, 413 und fehlgeschlagenen Aufträgen senden wir x-should-retry: false, damit die SDKs nicht automatisch wiederholen.

Limits

• Bis 500 MB und 6 Stunden pro Datei.
• Formate: MP3, WAV, FLAC, OGG, OPUS, WEBM, MKV, MP4, M4A, MOV, 3GP, AAC, AIFF und AMR. Bei Videos zählt nur die Tonspur.
• Höchstens 5 Aufträge gleichzeitig in Bearbeitung pro Konto.
• Ergebnisse bleiben 7 Tage abrufbar und werden danach gelöscht.

Wiederholungen

Die SDKs wiederholen Anfragen bei Zeitüberschreitung und Serverfehlern. Damit Sie nicht doppelt bezahlen, hängt sich eine Anfrage mit derselben Datei, demselben Modell und demselben prompt innerhalb von 24 Stunden an den bestehenden Auftrag an, solange dieser läuft oder fertig ist. Es wird nichts erneut abgebucht.

Lange Dateien

Die Anfrage bleibt offen, bis das Transkript fertig ist. Eine Stunde Audio dauert meist wenige Minuten, mit Pro etwas länger. Die SDKs brechen standardmässig nach 10 Minuten ab. Setzen Sie für lange Dateien timeout=1800 (Python) beziehungsweise timeout: 1800000 (Node). Läuft die Zeit trotzdem ab, hängt sich die Wiederholung an denselben Auftrag an; das Ergebnis finden Sie zudem im Dashboard.

Beispiele