Guida all’integrazione per Sviluppatori di Trooper.AI Blibs

Modelli e Prezzi

I nostri prezzi di base sono i seguenti. Potrebbero applicarsi tariffe aggiuntive per paese all’ordine di API Blib. Inoltre, Lei può usufruire delle nostre regolari promozioni Extra Credits!

* Offerta attuale: +15% Crediti Extra sul Suo pagamento da €160 questo mese. Paga €160 e riceva €200 sul Suo conto!

Come ordinare il Suo API Blib

Prima di utilizzare la nostra API deve ordinare il Suo API Blib sul nostro sito web: Ordini API Blib

Lei può scegliere il Suo Model e la Sua Region e, una volta implementato il modello desiderato, dovrebbe vedere qualcosa di simile in questo modo nel Suo Management Dashboard:

Prompt di Sistema Statico Gratuito

Offriamo uno system prompt gratuito fino a 1.024 caratteri. Lo system prompt gratuito è disponibile esclusivamente tramite il dashboard! I messaggi di sistema dinamici inviati tramite l'API vengono addebitati come di consueto. Clicchi su Azioni e vedrà il dialogo di modifica dello system prompt:

Avanti, ordini il Suo API Blib ora:

Ordini API Blib ora

Benchmark LLM 🧪

Se desidera confrontare i nostri endpoint LLM con altre piattaforme LLM, può utilizzare il nostro strumento gratuito di benchmarking della qualità LLM qui: Free LLM Quality Benchmark Ecco a cosa assomiglia:

Testi qualsiasi endpoint LLM compatibile con OpenAI con 25 controlli di qualità automatizzati — reasoning, coding, multilingual, structured output, tool calling e altro ancora.

URL di base

https://eu.router.trooper.ai/v1

Endpoint regionali per la residenza dei dati a livello nazionale:

Autenticazione

Tutte le richieste richiedono un token di tipo Bearer. Ottenga la Sua chiave API dal cruscotto di gestione .

Authorization: Bearer YOUR_TROOPER_KEY

Modelli disponibili

Attivi le rotte su trooper.ai/order-apiblib . Ogni rotta Le fornirà un nome modello da utilizzare nelle chiamate API.

Punti di erogazione

POST /v1/chat/completions

Endpoint standard compatibile con OpenAI per completamenti di chat.

GET /v1/models

Elenca i Suoi modelli attivati. Richiede autenticazione. Restituisce solo i modelli corrispondenti alla regione del dominio da Lei chiamato.

Ogni oggetto modello include:

Oggetto delle capacità:

Utilizzi capabilities.thinking per determinare se un modello accetta parametri di ragionamento prima dell'invio.

Esempio di risposta:

{
  "object": "list",
  "data": [
    {
      "id": "clara",
      "object": "model",
      "owned_by": "trooper_42",
      "created": 1700000000,
      "base_models": ["Ministral-3"],
      "context_length": 131072,
      "max_tokens": 131072,
      "capabilities": {
        "tools": true,
        "vision": true,
        "audio": false,
        "thinking": false,
        "json_mode": true,
        "token_budget": false
      },
      "supported_parameters": [
        "temperature", "top_p", "max_tokens", "stream",
        "response_format", "tools", "tool_choice"
      ]
    }
  ]
}

GET /health

Restituisce la disponibilità dell'endpoint e le informazioni sulla regione.

Ordini API Blib ora

Parametri della richiesta

Tutti i parametri seguono il formato dell’API OpenAI Chat Completions.

Obbligatorio

Facoltativo

Caratteristiche

Streaming

Streaming SSE standard, completamente compatibile con l’OpenAI SDK.

{ "stream": true }

Formato della risposta: data: {...}\n\n righe, terminate da data: [DONE]\n\n.

Modalità JSON

Richieda un output strutturato in formato JSON. Assicuri che non venga impostata solo la richiesta JSON nel messaggio di testo; Lei deve inoltre impostare almeno il parametro response_format su json_object!

Se il modello non riesce a produrre un JSON valido, non Le sarà addebitato nulla.

{ "response_format": { "type": "json_object" } }

Con uno schema:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "my_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "integer" }
        },
        "required": ["name", "age"]
      }
    }
  }
}

Visione (Immagini & PDF)

Invii immagini tramite URL o base64. I PDF vengono automaticamente convertiti in immagini delle pagine lato server.

{
  "messages": [{
    "role": "user",
    "content": [
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } },
      { "type": "text", "text": "Describe this image." }
    ]
  }]
}

Base64:

{
  "type": "image_url",
  "image_url": { "url": "data:image/png;base64,iVBOR..." }
}

• Le immagini vengono ridimensionate automaticamente e spogliate dei metadati (SSRF-safe).
• Il numero massimo di immagini e le loro dimensioni dipendono dalla configurazione del Suo percorso.
• Supportato su liv e clara routes.

Audio

Invii file audio nei messaggi multimodali. Supportato su liv. Durata massima di 30 secondi a causa dei limiti di Gemma 4. Se necessita di più tempo, divida l'audio in fette sovrapposte e invii una per volta con il risultato delle parti già trascodificate.

Pensiero / Ragionamento

Controlli se e con quale profondità il modello ragiona (chain-of-thought) prima di rispondere.

Abiliti il ragionamento standard:

{ "reasoning_effort": "medium" }

Abiliti il ragionamento approfondito per qualità massima:

{ "reasoning_effort": "high" }

Oppure tramite il reasoning oggetto:

{ "reasoning": { "effort": "high" } }

Disabiliti esplicitamente il ragionamento:

{ "reasoning_effort": "none" }

Per rimuovere il ragionamento dalla risposta (il pensiero avviene comunque, ma i token di ragionamento non vengono restituiti):

{ "reasoning": { "effort": "high", "exclude": true } }

Comportamento di Ragionamento può essere configurato anche per percorso nella dashboard di gestione. L'impostazione della dashboard controlla il comportamento predefinito e il modo in cui il ragionamento viene restituito:

• Disabilitato — Ragionamento disattivato per impostazione predefinita. Può comunque essere attivato per richiesta tramite "reasoning_effort": "medium" o "high".
• Taglio — Il ragionamento è attivo, ma i token di ragionamento vengono rimossi dalla risposta.
• Contenuto di Ragionamento — Ragionamento attivo, ragionamento restituito in un campo separato reasoning_content.
• Tag di Pensiero — Pensiero attivo, ragionamento restituito come tags all'interno del contenuto.

Recupero del ragionamento: se il modello entra in un loop di ragionamento, il router si riavvia automaticamente e restituisce una risposta utilizzabile.

Chiamata di Funzione / Strumenti

Formato standard degli OpenAI tools. Funziona con tutte le rotte.

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  }],
  "tool_choice": "auto"
}

Compressione Automatica del Contesto

Se il Suo input supera la finestra di contesto, il router comprime automaticamente la parte centrale della conversazione per adattarla — non è necessaria alcuna troncatura manuale.

Prompt di Sistema

Un prompt di sistema gratuito può essere configurato per ogni percorso nella dashboard di gestione. Viene aggiunto automaticamente a ogni richiesta e non fatturato.

Formato della risposta

Inviluppo di risposta standard OpenAI:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "clara",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Con la ragionamento abilitato, la risposta potrebbe includere reasoning_content accanto content.

Identificativo di transazione

Ogni risposta include x-transaction-id intestazione per riferimento di fatturazione e debug.

Gestione degli errori

Gli errori seguono il formato di invio degli errori di OpenAI:

{
  "error": {
    "message": "The model 'nonexistent' does not exist.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Codici di Errore

Fatturazione

• Prezzo per token — i token di input e output fatturati separatamente ogni milione di token.
• Nessun costo di inattività — paga solo quando effettua chiamate all'API.
• Credits pre-pagati — ricarichi il Suo saldo e lo utilizza secondo necessità.
• Token di sistema sono gratuiti (non fatturati).
• Richieste JSON fallite non vengono addebitate quando si utilizza la modalità JSON.
• Gli input di visione vengono fatturati per unità (immagini elaborate).

Ordini API Blib ora

Esempi di Integrazione

Visioni di esempi popolari di codice su come utilizzare un'API compatibile con OpenAI per l'inferenza LLM. Il router.trooper.ai deve essere sostituito con l'URL dell'endpoint mostrato nel Suo ordine API Blib!

Python (SDK OpenAI)

from openai import OpenAI

client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

response = client.chat.completions.create(
    model="clara",
    messages=[{"role": "user", "content": "Summarize this document."}],
    max_tokens=1024
)

print(response.choices[0].message.content)

Node.js (SDK di OpenAI)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.trooper.ai/v1",
  apiKey: "YOUR_TROOPER_KEY",
});

const response = await client.chat.completions.create({
  model: "nikola",
  messages: [{ role: "user", content: "Write a unit test for this function." }],
  max_tokens: 2048,
});

console.log(response.choices[0].message.content);

Python con Streaming

from openai import OpenAI

client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

stream = client.chat.completions.create(
    model="liv",
    messages=[{"role": "user", "content": "Explain quantum computing."}],
    max_tokens=2048,
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

Modalità JSON

import json
from openai import OpenAI

client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

response = client.chat.completions.create(
    model="clara",
    messages=[{"role": "user", "content": "List the 3 largest EU countries as JSON with name and population."}],
    max_tokens=512,
    response_format={"type": "json_object"}
)

data = json.loads(response.choices[0].message.content)
print(data)

Vision (Analisi dell'Immagine)

from openai import OpenAI

client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

response = client.chat.completions.create(
    model="clara",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/invoice.png"}},
            {"type": "text", "text": "Extract all line items from this invoice as JSON."}
        ]
    }],
    max_tokens=2048,
    response_format={"type": "json_object"}
)

print(response.choices[0].message.content)

Chiamata di funzione

from openai import OpenAI

client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="nikola",
    messages=[{"role": "user", "content": "What's the weather in Berlin?"}],
    tools=tools,
    tool_choice="auto",
    max_tokens=512
)

tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    print(tool_calls[0].function.name, tool_calls[0].function.arguments)

LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY",
    model="clara",
    max_tokens=1024
)

response = llm.invoke("Extract all dates from the following text: ...")
print(response.content)

LlamaIndex

from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    api_base="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY",
    model="nikola",
    max_tokens=2048
)

response = llm.complete("Explain the EU AI Act in simple terms.")
print(response.text)

cURL

curl https://router.trooper.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TROOPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clara",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 512
  }'

Migrazione da OpenAI

Modifica in una riga — aggiornare l’URL di base e la chiave API:

# Before (OpenAI)
client = OpenAI(api_key="sk-...")

# After (Trooper.AI)
client = OpenAI(
    base_url="https://router.trooper.ai/v1",
    api_key="YOUR_TROOPER_KEY"
)

Tutto il resto rimane invariato: formato della richiesta, schema di risposta, streaming, strumenti, modalità JSON.

Residenza dei dati e conformità normativa

• Tutto l'elaborazione avviene su centri dati certificati ISO/IEC 27001 in Germania e nell'UE.
• Nessun trattamento dei dati di conservazione — prompt e risposte elaborati esclusivamente in RAM, mai memorizzati.
• Conforme al GDPR — nessun trasferimento transfrontaliero dei dati, nessuna formazione del modello sui suoi dati.
• Routing a livello di paese disponibile (DE, NL o UE più ampia).

Ordini API Blib ora