Una riga di codice, e giri nell’Unione europea.

Quickstart: la tua prima chiamata API

Crea una chiave nella tua dashboard, sotto Impostazioni, Chiavi API. Il segreto lo vedi una volta sola: dopo conserviamo solo un hash e il prefisso. Mettilo in una variabile d’ambiente, mai nel tuo repository.

curl https://api.europeanailab.eu/v1/chat/completions \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eu-standard",
    "messages": [{"role": "user", "content": "Spiega come funziona il reverse charge dell’IVA."}]
  }'

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UNION_API_KEY"],
    base_url="https://api.europeanailab.eu/v1",   # l’unica riga che cambia
)

resp = client.chat.completions.create(
    model="eu-standard",
    messages=[{"role": "user", "content": "Spiega come funziona il reverse charge dell’IVA."}],
)
print(resp.choices[0].message.content)

Tier dei modelli e finestre di contesto

Nel campo model passi un tier, non il nome di un modello. Così la tua integrazione continua a funzionare quando sostituiamo il modello sottostante, e lo faremo, perché i modelli open-weight vengono ritirati e superati.

Se superi la finestra di contesto di un tier ricevi un 400 con il massimo indicato: non tronchiamo mai il tuo prompt di nascosto.

Risposte in streaming

Lo streaming funziona come ti aspetti, con una differenza importante che devi conoscere, perché riguarda i tuoi soldi.

stream = client.chat.completions.create(
    model="eu-standard",
    messages=[{"role": "user", "content": "Scrivi un riassunto."}],
    stream=True,
    # Senza questo non arriva l’oggetto usage e non vedi il costo.
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:                      # ultimo chunk
        print("\n", chunk.usage)

Se interrompi uno stream a metà, paghi solo quello che è stato generato fino a quel momento. Se per la connessione interrotta non arriva il chunk con il consumo, stimiamo il consumo e lo correggiamo nella riconciliazione giornaliera con il nostro provider. Fino alla chiusura, quella riga compare nel tuo riepilogo consumi come estimated.

Function calling e uso dei tool

I tool seguono lo schema che conosci. Se un modello produce una chiamata a un tool che non corrisponde al tuo schema, la registriamo: nella versione 1 non la correggiamo di nascosto, perché riparare in silenzio il tuo output è peggio di un errore visibile.

tools = [{
    "type": "function",
    "function": {
        "name": "find_invoice",
        "description": "Cerca una fattura in base al numero.",
        "parameters": {
            "type": "object",
            "properties": {"number": {"type": "string"}},
            "required": ["number"],
        },
    },
}]

resp = client.chat.completions.create(
    model="eu-standard", messages=messages, tools=tools
)

Output strutturato con uno JSON schema

Passa uno JSON schema e valida la risposta dal tuo lato. Il nostro consiglio: valida sempre, anche quando il modello di solito si comporta bene.

resp = client.chat.completions.create(
    model="eu-standard",
    messages=[{"role": "user", "content": "Estrai il nome e l’importo."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "invoice",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "amount_eur": {"type": "number"},
                },
                "required": ["name", "amount_eur"],
            },
        },
    },
)

Header di risposta: costo, tier e instradamento

Ogni risposta ti dice cosa è successo. Non è un extra per il debug, è il punto: puoi verificare da solo di aver ricevuto quello che hai pagato.

Rate limit e tetti di spesa

C’è un limite per chiave e per account, più i tetti che imposti tu. Questi ultimi contano più di quanto sembri: senza un tetto, una chiave finita in mani sbagliate o un ciclo infinito nel tuo codice possono svuotare un saldo in una notte.

• Richieste al minuto, per chiave e per account.
• Tetto giornaliero e mensile in euro, configurabile per chiave.
• Nuovi account: al massimo 25 € al giorno per le prime 48 ore, qualunque sia il saldo.
• Se in un’ora vediamo più di dieci volte la tua media settimanale, mettiamo in pausa la chiave in automatico e ti mandiamo un’email. Meglio un falso allarme che un portafoglio vuoto.
• Una richiesta parte solo se il tuo saldo è almeno 0,05 €.

Codici di errore e cosa fare

Le richieste fallite non ti costano nulla: se non è arrivata una risposta utilizzabile, dal tuo saldo non si scala niente.

Uso corretto e policy di utilizzo

Rifiutiamo istruzioni per armi, malware e frodi, e materiale che danneggia i minori. Questi rifiuti sono definitivi: non inoltriamo mai una richiesta del genere a un altro modello per strappargli comunque una risposta.

Un modello che rifiuta una domanda legittima su politica, storia o un tema socialmente delicato è un’altra cosa: lo trattiamo come un difetto e mandiamo la richiesta a un modello senza quel punto cieco. Lo vedi nell’header X-EU-Routed: censorship.

Uno dei nostri modelli ha una licenza con una propria policy di utilizzo. Quella policy vale per intero: il reindirizzamento non aggira i termini di licenza.

Non sai se il tuo caso d’uso rientra? Scrivi a hello@europeanailab.eu. Una risposta prima costa meno a entrambi di una chiave bloccata dopo.

Domande frequenti

Le domande che arrivano per email prima che qualcuno crei una chiave: con cosa è compatibile l’API, quanto costa una richiesta e dove gira.

Spostare un’integrazione esistente richiede tre righe: la chiave, il base URL e il nome di un tier. Tutta la modifica, più quello che non si porta dietro, è in il passaggio in tre righe. Hai ancora dubbi? Le tariffe per tier sono nella pagina dei prezzi, il modello e la licenza dietro ogni tier in trasparenza sull’AI e cosa succede durante un disservizio nella pagina di stato. Due letture più lunghe: quanto costa un’API AI a token e dove finiscono davvero i tuoi prompt.