Streaming

Imposta stream: true su Chat completions, Responses o Completions per ricevere i token man mano che vengono generati. La risposta usa i server-sent events (Content-Type: text/event-stream). api14 ti inoltra i byte dell'upstream appena arrivano, senza bufferizzarli.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const stream = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector databases in two sentences."
    }
  ],
  "stream": true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Formato degli eventi

Ogni evento è una riga data: che contiene un chunk JSON. Lo stream termina con data: [DONE].

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"}}]}

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{"content":"lo!"}}]}

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":3,"total_tokens":13,"cost":0.0000085}}

data: [DONE]

• L'ultimo chunk prima di [DONE] contiene usage, incluso cost in USD. Non ti serve stream_options.include_usage. Il report sull'utilizzo è sempre attivo.
• L'id è lo stesso in ogni chunk. È l'id della generazione, che puoi passare alla Consultazione delle generazioni.
• Alcuni provider inviano righe di commento SSE (che iniziano con :) per mantenere attiva la connessione. I client SSE e gli SDK di OpenAI le ignorano. Se analizzi lo stream da solo, salta le righe che iniziano con :.

Fatturazione degli stream

Il gateway legge il chunk finale con usage mentre inoltra lo stream e addebita il tuo saldo alla chiusura dello stream.

Disconnettersi non annulla l'addebito. Se chiudi la connessione prima che lo stream sia finito, il provider upstream potrebbe continuare a generare e addebitare comunque. In quel caso api14 legge il costo dal record della generazione. Per limitare il costo, imposta max_tokens.

Errori durante uno stream

Gli errori prima del primo byte, come una chiave non valida, un saldo insufficiente o un modello sconosciuto, restituiscono un normale errore JSON con stato 4xx o 5xx. Vedi Errori. Se un provider fallisce a metà stream, lo stream può terminare con un chunk che contiene un oggetto error e finish_reason: "error":

{ "error": { "code": 502, "message": "Provider disconnected" }, "choices": [{ "delta": { "content": "" }, "finish_reason": "error" }] }

Controlla sempre il finish_reason dell'ultimo chunk.

Suggerimenti

• Proxy e piattaforme serverless a volte bufferizzano le risposte. Disattiva il buffering delle risposte (ad es. X-Accel-Buffering: no su nginx) se inoltri lo stream ai browser.
• Le chiamate agli strumenti arrivano in streaming come frammenti delta.tool_calls. Unisci le stringhe arguments per index prima di analizzarle. Vedi Tool calling.
• I modelli di ragionamento trasmettono il loro ragionamento in delta.reasoning prima della risposta. Vedi Ragionamento.