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, 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.Up to 10 active keys. 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 (10,000 characters).
`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.
`NAME_SUBSTITUTION`	422	The model changed the name in the greeting. Already retried once; retry, or rephrase the opening.
`PLACEHOLDER_LEAK`	422	The model added a template placeholder such as [Your name]. Already retried once; retry the request.
`UNPARSEABLE_OUTPUT`	422	With automatic source detection, the model's answer could not be read. Already retried once; retry, or set source_lang.
`TRANSLATION_INCOMPLETE`	422	The translation was cut off before the end. Split the text into shorter parts.
`USAGE_LIMIT_EXCEEDED`	429	Monthly included quota exhausted.
`INTERNAL_ERROR`	500	Unexpected server error. Retry with backoff; contact support if it persists.
`UPSTREAM_UNAVAILABLE`	503	The translation model is temporarily unavailable. Retry with backoff.
`UPSTREAM_BUSY`	503	The translation model is busy. Wait for the Retry-After header (seconds), then retry.
`TRANSLATION_TIMEOUT`	504	The translation took longer than 90 seconds. Retry, or send a shorter text.

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