Documentazione

Inferenza IA

Guida rapida

Ottieni la tua prima risposta in poche righe. L'API di inferenza è compatibile con OpenAI, quindi puoi puntare qualsiasi SDK di OpenAI all'URL di base qui sotto e autenticarti con la tua chiave API.

URL di base
https://api.nebux.cloud/v1

Installazione

index.ts
npm install openai
index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Recommend me a book" },
    { role: "assistant", content: "Try The Shadow of the Wind" },
    { role: "user", content: "And a similar one?" },
  ],
});

console.log(completion.choices[0].message.content);
RISPOSTA
{
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "If you liked it, try Nada, by Carmen Laforet."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 13,
    "total_tokens": 60
  }
}

Autenticazione

Tutte le richieste devono includere la tua chiave API nell'header Authorization come token Bearer.

Genera e gestisci le tue chiavi API dal pannello. Gestisci le chiavi API

Mantieni segreta la tua chiave API. Non esporla mai nel codice lato client e non includerla nel controllo di versione.

Header
Authorization: Bearer your-api-key

Chat completions

Genera una risposta del modello per una conversazione. Invia un elenco di messaggi e ricevi la risposta dell'assistente.

Parametri

modelstringobbligatorio

ID del modello da usare.

messagesarrayobbligatorio

La conversazione fino a questo momento, come elenco di messaggi.

rolestring

Il ruolo dell'autore del messaggio.

systemDefinisce il comportamento e il contesto dell'assistente.
userUn messaggio dell'utente finale.
assistantUna risposta precedente del modello.
toolIl risultato di una chiamata a uno strumento, restituito al modello.
contentstring

Il contenuto testuale del messaggio.

namestring

Un nome facoltativo per distinguere i partecipanti con lo stesso ruolo.

temperaturenumberfacoltativo

Temperatura di campionamento tra 0 e 2. Valori più alti rendono l'output più casuale; valori più bassi, più mirato e deterministico.

top_pnumberfacoltativo

Campionamento nucleus: considera solo i token che compongono la massa di probabilità top_p. Usa questo parametro o temperature, non entrambi.

max_tokensnumberfacoltativo

Il numero massimo di token da generare nella risposta.

stopstring | arrayfacoltativo

Fino a quattro sequenze in corrispondenza delle quali la generazione si ferma. La sequenza di stop non è inclusa nell'output.

frequency_penaltynumberfacoltativo

Tra -2 e 2. I valori positivi penalizzano i token in base a quante volte sono già comparsi, riducendo le ripetizioni.

presence_penaltynumberfacoltativo

Tra -2 e 2. I valori positivi penalizzano i token che sono già comparsi, spingendo il modello a introdurre nuovi argomenti.

seednumberfacoltativo

Se impostato, il modello campiona nel modo più deterministico possibile, così che richieste ripetute con gli stessi parametri restituiscano risultati simili.

nnumberfacoltativo

Quante risposte generare per ogni richiesta.

streambooleanfacoltativo

Trasmette la risposta come Server-Sent Events. Vedi Streaming.

response_formatobjectfacoltativo

Vincola il formato dell'output, ad es. a JSON. Vedi Modalità JSON.

toolsarrayfacoltativo

Un elenco di funzioni che il modello può invocare. Vedi Strumenti.

chat_template_kwargsobjectfacoltativo

Attiva il ragionamento per questa richiesta. Vedi Ragionamento.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Recommend me a book" },
    { role: "assistant", content: "Try The Shadow of the Wind" },
    { role: "user", content: "And a similar one?" },
  ],
});

console.log(completion.choices[0].message.content);
RISPOSTA
{
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "If you liked it, try Nada, by Carmen Laforet."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 13,
    "total_tokens": 60
  }
}

Streaming

Imposta stream su true per ricevere la risposta come Server-Sent Events, con i token che arrivano in modo incrementale man mano che vengono generati. Lo stream termina con una riga data: [DONE].

Parametri

streambooleanobbligatorio

Imposta su true per trasmettere la risposta come Server-Sent Events.

stream_optionsobjectfacoltativo

Opzioni che si applicano solo in streaming.

include_usageboolean

Emette un frammento finale aggiuntivo con l'utilizzo di token dell'intera richiesta.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const stream = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [{ role: "user", content: "Which running shoes do you recommend?" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
RISPOSTA
data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "role": "assistant" }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "content": "For asphalt," }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": { "content": " a neutral shoe with good cushioning" }, "finish_reason": null }]
}

data: {
  "id": "chatcmpl-8f3a2b1c9d",
  "object": "chat.completion.chunk",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [{ "index": 0, "delta": {}, "finish_reason": "stop" }]
}

data: [DONE]

Ragionamento

Lascia che il modello pensi prima di rispondere. È disattivato di default: invia chat_template_kwargs con enable_thinking impostato su true per attivarlo in una richiesta. Il ragionamento torna in reasoning, accanto a content e non al suo interno, quindi puoi mostrarlo, registrarlo o ignorarlo. Viene fatturato come token di output, come il resto della risposta, e una risposta ragionata può consumarne diverse volte di più.

Parametri

chat_template_kwargsobjectobbligatorio

Argomenti aggiuntivi per il template di prompt del modello. È supportato solo enable_thinking.

enable_thinkingboolean

true chiede al modello di ragionare prima di rispondere. Di default, false.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const res = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "user", content: "A coffee is 1.20. What are 7 with 15% off?" },
  ],
  // chat_template_kwargs is outside the OpenAI library's types,
  // so it travels as an extra request parameter.
  // The other option is calling POST https://api.nebux.cloud/v1/chat/completions
  // directly.
  // @ts-expect-error
  chat_template_kwargs: {"enable_thinking": true},
});

console.log(res.choices[0].message.content);
RISPOSTA
{
  "id": "chatcmpl-6b1d05e37a",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning": "7 x 1.20 = 8.40. A 15% discount leaves 85%, so 8.40 x 0.85 = 7.14.",
        "content": "7.14 EUR"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 61,
    "total_tokens": 83
  }
}

Modalità JSON

Imposta response_format su json_object per obbligare il modello a emettere JSON sintatticamente valido. Indica comunque al modello di produrre JSON anche in un messaggio di sistema o dell'utente.

Parametri

response_formatobjectobbligatorio

Un oggetto che specifica il formato che il modello deve produrre.

typestring

Imposta su json_object per attivare la modalità JSON.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [
    { role: "system", content: "Classify each comment as good or bad, keeping its id. Reply as JSON." },
    { role: "user", content: "1: Great! 2: Awful 3: Good 4: Slow" },
  ],
  response_format: { type: "json_object" },
});

console.log(JSON.parse(completion.choices[0].message.content));
RISPOSTA
{
  "id": "chatcmpl-2a7c4e9f10",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"good\": [{\"id\": 1, \"comment\": \"Great!\"}, {\"id\": 3, \"comment\": \"Good\"}], \"bad\": [{\"id\": 2, \"comment\": \"Awful\"}, {\"id\": 4, \"comment\": \"Slow\"}]}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 51,
    "total_tokens": 109
  }
}

Strumenti

Fornisci un elenco di funzioni che il modello può invocare. Quando il modello decide di usarne una, restituisce la chiamata in tool_calls invece di una risposta testuale; tu esegui la funzione e rimandi il risultato come messaggio tool.

Parametri

toolsarrayobbligatorio

Un elenco di funzioni che il modello può invocare.

typestring

Il tipo di strumento. Al momento è supportato solo function.

functionobject

La definizione della funzione.

namestring

Il nome della funzione da invocare.

descriptionstring

Una descrizione di ciò che fa la funzione, usata dal modello per decidere quando invocarla.

parametersobject

I parametri della funzione, descritti come oggetto JSON Schema.

tool_choicestring | objectfacoltativo

Controlla l'uso degli strumenti: auto, none, required, oppure una funzione specifica da forzare.

index.ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-api-key",
  baseURL: "https://api.nebux.cloud/v1",
});

const completion = await client.chat.completions.create({
  model: "qwen3-14b",
  messages: [{ role: "user", content: "What's the weather in València?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather for a location",
        parameters: {
          type: "object",
          properties: { location: { type: "string" } },
          required: ["location"],
        },
      },
    },
  ],
});

console.log(completion.choices[0].message.tool_calls);
RISPOSTA
{
  "id": "chatcmpl-5b1d8e2a34",
  "object": "chat.completion",
  "created": 1719763200,
  "model": "qwen3-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_a1b2c3",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"València\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 19,
    "total_tokens": 101
  }
}

Errori

Le richieste non riuscite restituiscono un codice di stato HTTP standard e un corpo JSON con un oggetto error che descrive cosa è andato storto.

Codici di stato

400invalid_request_errorLa richiesta era malformata o un parametro non era valido.
401invalid_api_keyLa chiave API manca o non è valida.
404model_not_foundIl modello richiesto non esiste o non è disponibile per la tua organizzazione.
429rate_limit_exceededHai superato il tuo limite di richieste. Riprova dopo una breve attesa.
500server_errorSi è verificato un errore imprevisto durante l'elaborazione della richiesta.
503engine_overloadedIl servizio è temporaneamente sovraccarico. Riprova dopo una breve attesa.
Vedi il riferimento completo degli errori
RISPOSTA
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Funzionalità non supportate

Questa API è compatibile con l'interfaccia chat completions di OpenAI. Le seguenti funzionalità di OpenAI non sono disponibili.

  • L'API Embeddings.
  • L'API Assistants (assistants, threads e runs).
  • Fine-tuning.
  • L'API Batch.
  • L'API Files e i caricamenti, e i vector store.
  • Endpoint audio (sintesi vocale e trascrizione).
  • Generazione di immagini.
  • L'API Moderations.
  • L'API Realtime.