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, 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.Fino a 10 chiavi attive. 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 (10.000 caratteri).
`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.
`NAME_SUBSTITUTION`	422	Il modello ha cambiato il nome nel saluto. Già ripetuto una volta; riprova o riformula l'apertura.
`PLACEHOLDER_LEAK`	422	Il modello ha aggiunto un segnaposto come [Il tuo nome]. Già ripetuto una volta; invia di nuovo la richiesta.
`UNPARSEABLE_OUTPUT`	422	Con il rilevamento automatico della lingua, la risposta del modello non era leggibile. Già ripetuto una volta; riprova o indica source_lang.
`TRANSLATION_INCOMPLETE`	422	La traduzione è stata interrotta prima della fine. Dividi il testo in parti più brevi.
`USAGE_LIMIT_EXCEEDED`	429	Quota mensile inclusa esaurita.
`INTERNAL_ERROR`	500	Errore server imprevisto. Riprovate con backoff; contattate il supporto se persiste.
`UPSTREAM_UNAVAILABLE`	503	Il modello di traduzione non è temporaneamente disponibile. Riprova con backoff.
`UPSTREAM_BUSY`	503	Il modello di traduzione è sovraccarico. Attendi i secondi indicati nell'header Retry-After, poi riprova.
`TRANSLATION_TIMEOUT`	504	La traduzione ha richiesto più di 90 secondi. Riprova o invia un testo più breve.

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