Documentazione per sviluppatori

Avvio rapido

Autenticarsi, inviare una traduzione, gestire gli errori. Affianca questa guida con la reference interattiva dell'API per tutti i dettagli dello schema.

Apri reference API Torna ai prezzi

1. Abbonarsi e creare una chiave API

Le traduzioni sono fatturate per carattere su un abbonamento B2B attivo. Inizia con 14 giorni di prova gratuita su Starter, poi genera le chiavi dalla pagina account.

1.Abbonatevi dalla pagina dei prezzi (carta richiesta, nessun addebito durante la prova).
2.Aprite la pagina account e generate una chiave API. La chiave completa è mostrata una volta sola — trattatela come una password.
3.Starter consente 1 chiave attiva, Business 10. Revoca e rotazione in qualsiasi momento.

2. Autenticare ogni richiesta

Inviate la chiave nell'header X-API-Key. Niente OAuth, niente scadenza — le chiavi sono valide finché non vengono revocate.

http

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

3. Prima traduzione

POST a /api/public/v1/translate con testo, lingua sorgente e lingua di destinazione. La risposta contiene la traduzione e i caratteri fatturati.

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

Lingue e opzioni

Qualsiasi combinazione sorgente/destinazione tra le lingue supportate è valida, inclusi svizzero-tedesco e romancio. Impostate source_lang su auto per far rilevare la sorgente al motore.

deGerman

gswSwiss German

frFrench

itItalian

enEnglish

rmRomansh

Formalità

Passate formality=informal o formality=formal quando traducete in tedesco, francese o italiano per controllare la forma di cortesia (du/Sie, tu/vous, tu/Lei). Default auto.

Dialetti svizzero-tedeschi

Quando target_lang è gsw, scegliete un dialetto per la sfumatura regionale. Senza specifica, viene usato un Bärndütsch neutro.

bernzurichbaselstgallenwallisluzern

Limiti e codici di errore

Gli errori restituiscono un oggetto detail strutturato con un campo code stabile e un messaggio leggibile. I codici 4xx sono segnali affidabili su cui basare la logica.

Codice	HTTP	Significato
`UNSUPPORTED_LANGUAGE`	400	Codice lingua sorgente o destinazione non supportato.
`UNSUPPORTED_DIALECT`	400	Dialetto non riconosciuto. Vedi i codici validi sopra.
`TEXT_TOO_LONG`	400	Il testo supera il limite di caratteri per richiesta del tuo piano (10k su Starter, 50k su Business).
`INVALID_API_KEY`	401	Header X-API-Key mancante o revocato.
`SUSPICIOUS_OUTPUT`	422	Il modello ha prodotto un output non simile a una traduzione. Ritentate o semplificate l'input.
`USAGE_LIMIT_EXCEEDED`	429	Quota mensile inclusa esaurita. L'abbonamento continua — Business fattura l'eccedenza, Starter blocca fino al periodo successivo.
`INTERNAL_ERROR`	500	Errore server imprevisto. Riprovate con backoff; contattate il supporto se persiste.

Verifica del consumo

Interrogate /usage per mostrare il consumo nella vostra dashboard, inviare avvisi prima dell'eccedenza o regolare i carichi non essenziali.

bash

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

Domande? Scrivete a gruezi@helvetra.ch