Developer documentation

Quickstart

Authenticate, send a translation, handle errors. Pair this guide with the interactive API reference for full schema details.

Open API reference Back to pricing

1. Subscribe and create an API key

Translation calls are billed per character against an active B2B subscription. Start a free 14-day trial on Starter, then generate keys from your account page.

1.Subscribe on the pricing page (card required, no charge during trial).
2.Open your account page and generate an API key. The full key is shown once — store it like a password.
3.Starter allows 1 active key, Business allows 10. Revoke and rotate at any time.

2. Authenticate every request

Send your key in the X-API-Key header. There is no OAuth dance, no expiry — keys are valid until you revoke them.

http

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

3. Make your first translation

POST to /api/public/v1/translate with the text, source language, and target language. The response includes the translation and the character count that was billed.

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

Languages and options

Any source/target combination among the supported languages is valid, including Swiss German and Romansh. Set source_lang to auto to let the engine detect the source.

deGerman

gswSwiss German

frFrench

itItalian

enEnglish

rmRomansh

Formality

Pass formality=informal or formality=formal when translating to German, French or Italian to control the address form (du/Sie, tu/vous, tu/Lei). Defaults to auto.

Swiss German dialects

When target_lang is gsw, pick a dialect for the regional flavour. Defaults to a neutral Bernese German if omitted.

bernzurichbaselstgallenwallisluzern

Limits and error codes

Errors return a structured detail object with a stable code field plus a human message. The 4xx codes are reliable signals you can branch on.

Code	HTTP	Meaning
`UNSUPPORTED_LANGUAGE`	400	Source or target language code is not supported.
`UNSUPPORTED_DIALECT`	400	Dialect not recognised. See the list of valid dialect codes above.
`TEXT_TOO_LONG`	400	Text exceeds the per-request character limit for your tier (10k on Starter, 50k on Business).
`INVALID_API_KEY`	401	Missing or revoked X-API-Key header.
`SUSPICIOUS_OUTPUT`	422	Model produced output that did not look like a translation. Retry, or simplify the input.
`USAGE_LIMIT_EXCEEDED`	429	Monthly included quota exhausted. Subscription continues — overage applies on Business; Starter blocks until the next period.
`INTERNAL_ERROR`	500	Unexpected server error. Retry with backoff; contact support if it persists.

Check your usage

Poll /usage to surface consumption in your own dashboard, send proactive alerts before overage, or throttle non-essential workloads.

bash

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

Questions? Write to gruezi@helvetra.ch