Documentation développeurs

Démarrage rapide

Authentifier, envoyer une traduction, gérer les erreurs. Complétez ce guide avec la référence interactive de l'API pour tous les détails du schéma.

Ouvrir la référence API Retour aux tarifs

1. Souscrire et créer une clé API

Les traductions sont facturées au caractère via un abonnement B2B actif. Commencez par 14 jours d'essai gratuit sur Starter, puis générez des clés depuis la page de votre compte.

1.Souscrivez sur la page des tarifs (carte requise, aucun débit pendant l'essai).
2.Ouvrez la page de votre compte et générez une clé API. La clé complète n'est affichée qu'une fois — traitez-la comme un mot de passe.
3.Starter autorise 1 clé active, Business 10. Révocation et rotation à tout moment.

2. Authentifier chaque requête

Envoyez votre clé dans l'en-tête X-API-Key. Pas d'OAuth, pas d'expiration — les clés sont valides jusqu'à révocation.

http

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

3. Faire votre première traduction

POST sur /api/public/v1/translate avec le texte, la langue source et la langue cible. La réponse contient la traduction et le nombre de caractères facturés.

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"
  }'

Langues et options

Toute combinaison source/cible parmi les langues prises en charge est valide, y compris le suisse-allemand et le romanche. Mettez source_lang à auto pour laisser le moteur détecter la source.

deGerman

gswSwiss German

frFrench

itItalian

enEnglish

rmRomansh

Formalité

Passez formality=informal ou formality=formal pour les traductions vers l'allemand, le français ou l'italien afin de contrôler la forme d'adresse (du/Sie, tu/vous, tu/Lei). Par défaut auto.

Dialectes suisse-allemands

Quand target_lang vaut gsw, choisissez un dialecte pour la couleur régionale. Sans précision, un Bärndütsch neutre est utilisé.

bernzurichbaselstgallenwallisluzern

Limites et codes d'erreur

Les erreurs renvoient un objet detail structuré avec un champ code stable et un message humain. Les codes 4xx sont des signaux fiables pour brancher votre logique.

Code	HTTP	Signification
`UNSUPPORTED_LANGUAGE`	400	Code de langue source ou cible non pris en charge.
`UNSUPPORTED_DIALECT`	400	Dialecte non reconnu. Voyez la liste des codes valides ci-dessus.
`TEXT_TOO_LONG`	400	Le texte dépasse la limite de caractères par requête de votre offre (10k sur Starter, 50k sur Business).
`INVALID_API_KEY`	401	En-tête X-API-Key manquant ou révoqué.
`SUSPICIOUS_OUTPUT`	422	Le modèle a produit une sortie qui ne ressemble pas à une traduction. Réessayez ou simplifiez l'entrée.
`USAGE_LIMIT_EXCEEDED`	429	Quota mensuel inclus épuisé. L'abonnement continue — Business facture l'excédent, Starter bloque jusqu'à la prochaine période.
`INTERNAL_ERROR`	500	Erreur serveur inattendue. Réessayez avec backoff ; contactez le support si elle persiste.

Vérifier votre consommation

Interrogez /usage pour afficher la consommation dans votre propre tableau de bord, envoyer des alertes avant dépassement, ou limiter les charges non essentielles.

bash

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

Des questions ? Écrivez à gruezi@helvetra.ch