Entwicklerdokumentation

Schnellstart

Authentifizieren, Übersetzung senden, Fehler behandeln. Ergänzen Sie diese Anleitung mit der interaktiven API-Referenz für alle Schema-Details.

API-Referenz öffnen Zurück zu den Preisen

1. Abonnement abschliessen und API-Schlüssel erstellen

Übersetzungen werden pro Zeichen über ein aktives B2B-Abonnement abgerechnet. Starten Sie mit 14 Tagen Gratis-Test auf Starter und erstellen Sie dann Schlüssel auf der Konto-Seite.

1.Abonnement auf der Preisseite starten (Kreditkarte erforderlich, keine Belastung während des Tests).
2.Konto-Seite öffnen und einen API-Schlüssel erstellen. Der vollständige Schlüssel wird einmal angezeigt — wie ein Passwort behandeln.
3.Starter erlaubt 1 aktiven Schlüssel, Business 10. Jederzeit widerrufen und rotieren.

2. Jede Anfrage authentifizieren

Senden Sie Ihren Schlüssel im X-API-Key-Header. Kein OAuth, kein Ablauf — Schlüssel gelten, bis Sie sie widerrufen.

http

X-API-Key: hv_live_••••••••••••••••••••••••••••••••

3. Erste Übersetzung erstellen

POST an /api/public/v1/translate mit Text, Quellsprache und Zielsprache. Die Antwort enthält die Übersetzung und die abgerechneten Zeichen.

bash

curl -X POST https://helvetra.ch/api/public/v1/translate \
  -H "X-API-Key: $HELVETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Grüezi mitenand!",
    "source_lang": "gsw",
    "target_lang": "en"
  }'

Sprachen und Optionen

Jede Kombination unter den unterstützten Sprachen ist gültig, einschliesslich Schweizerdeutsch und Rumantsch. Setzen Sie source_lang auf auto, damit die Engine die Quelle erkennt.

deGerman

gswSwiss German

frFrench

itItalian

enEnglish

rmRomansh

Anrede

Geben Sie formality=informal oder formality=formal an, wenn Sie ins Deutsche, Französische oder Italienische übersetzen, um Du/Sie, tu/vous, tu/Lei zu steuern. Standard ist auto.

Schweizerdeutsch-Dialekte

Wenn target_lang gsw ist, wählen Sie einen Dialekt für die regionale Färbung. Ohne Angabe wird ein neutrales Bärndütsch verwendet.

bernzurichbaselstgallenwallisluzern

Limits und Fehlercodes

Fehler liefern ein strukturiertes Detail-Objekt mit einem stabilen code-Feld und einer Nachricht für Menschen. Die 4xx-Codes sind zuverlässige Signale für Verzweigungen.

Code	HTTP	Bedeutung
`UNSUPPORTED_LANGUAGE`	400	Quell- oder Zielsprachcode wird nicht unterstützt.
`UNSUPPORTED_DIALECT`	400	Dialekt nicht erkannt. Liste gültiger Codes oben.
`TEXT_TOO_LONG`	400	Text überschreitet das Zeichenlimit pro Anfrage Ihres Tarifs (10k auf Starter, 50k auf Business).
`INVALID_API_KEY`	401	X-API-Key-Header fehlt oder wurde widerrufen.
`SUSPICIOUS_OUTPUT`	422	Modell lieferte eine Ausgabe, die nicht wie eine Übersetzung aussah. Erneut versuchen oder Eingabe vereinfachen.
`USAGE_LIMIT_EXCEEDED`	429	Monatliches Inklusivkontingent erschöpft. Abo läuft weiter — Business mit Overage, Starter blockiert bis zur nächsten Periode.
`INTERNAL_ERROR`	500	Unerwarteter Serverfehler. Mit Backoff erneut versuchen; bei Anhalten Support kontaktieren.

Nutzung abfragen

Rufen Sie /usage ab, um den Verbrauch im eigenen Dashboard anzuzeigen, eigene Alarme vor Overage zu senden oder Hintergrund-Workloads zu drosseln.

bash

curl https://helvetra.ch/api/public/v1/usage \
  -H "X-API-Key: $HELVETRA_API_KEY"

Fragen? Schreiben Sie an gruezi@helvetra.ch