Chat Completions

Panoramica

L’endpoint Chat Completions è l’API più utilizzata per interagire con i large language model. Accetta una conversazione composta da più messaggi e restituisce la risposta del modello. CometAPI instrada questo endpoint verso più provider — tra cui OpenAI, Anthropic Claude (tramite livello di compatibilità), Google Gemini e altri — attraverso un’unica interfaccia unificata. Puoi passare da un modello all’altro semplicemente modificando il parametro model.

Questo endpoint segue il formato OpenAI Chat Completions. La maggior parte degli SDK e degli strumenti compatibili con OpenAI funziona con CometAPI cambiando base_url in https://api.cometapi.com/v1.

Note importanti

Comportamento specifico del modello — Modelli diversi possono supportare sottoinsiemi diversi di parametri e restituire campi di risposta leggermente differenti. Ad esempio, reasoning_effort si applica solo ai modelli di reasoning (serie o, GPT-5.1+), e alcuni modelli potrebbero non supportare logprobs o n > 1.

Pass-through della risposta — CometAPI inoltra le risposte del modello senza modifiche (tranne la normalizzazione del formato durante l’instradamento tra provider), assicurandoti di ricevere un output coerente con l’API originale.

Modelli OpenAI Pro — Per i modelli della serie OpenAI Pro (ad esempio o1-pro), utilizza invece l’endpoint responses.

Ruoli dei messaggi

Role	Description
`system`	Imposta il comportamento e la personalità dell’assistente. Va posizionato all’inizio della conversazione.
`developer`	Sostituisce `system` per i modelli più recenti (o1+). Fornisce istruzioni che il modello deve seguire indipendentemente dall’input dell’utente.
`user`	Messaggi dell’utente finale.
`assistant`	Risposte precedenti del modello, usate per mantenere la cronologia della conversazione.
`tool`	Risultati delle chiamate a tool/function. Deve includere `tool_call_id` corrispondente alla chiamata tool originale.

Per i modelli più recenti (GPT-4.1, serie GPT-5, serie o), preferisci developer a system per i messaggi di istruzione. Entrambi funzionano, ma developer offre un comportamento più rigoroso nel seguire le istruzioni.

Input Multimodal

Molti modelli supportano immagini e audio insieme al testo. Usa il formato array per content per inviare messaggi multimodali:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this image"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    }
  ]
}

Il parametro detail controlla il livello di profondità dell’analisi dell’immagine:

low — più veloce, usa meno token (costo fisso)
high — analisi dettagliata, consumo di più token
auto — decide il modello (predefinito)

Streaming

Quando stream è impostato su true, la risposta viene fornita come Server-Sent Events (SSE). Ogni evento contiene un oggetto chat.completion.chunk con contenuto incrementale:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Per includere le statistiche di utilizzo dei token nelle risposte in streaming, imposta stream_options.include_usage su true. I dati di utilizzo compaiono nell’ultimo chunk prima di [DONE].

Structured Outputs

Forza il model a restituire un JSON valido che corrisponda a uno schema specifico usando response_format:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        },
        "required": ["answer", "confidence"],
        "additionalProperties": false
      }
    }
  }
}

La modalità JSON Schema (json_schema) garantisce che l’output corrisponda esattamente al tuo schema. La modalità JSON Object (json_object) garantisce solo un JSON valido — la struttura non viene applicata.

Tool / Function Calling

Abilita il model a chiamare funzioni esterne fornendo le definizioni dei tool:

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

Quando il model decide di chiamare un tool, la risposta avrà finish_reason: "tool_calls" e l’array message.tool_calls conterrà il nome della funzione e gli argomenti. A quel punto esegui la funzione e rimanda il risultato come messaggio tool con il tool_call_id corrispondente.

Response Fields

Field	Description
`id`	Identificatore univoco della completion (ad es. `chatcmpl-abc123`).
`object`	Sempre `chat.completion`.
`model`	Il model che ha generato la risposta (può includere un suffisso di versione).
`choices`	Array di scelte di completion (tipicamente 1 a meno che `n` > 1).
`choices[].message`	Il messaggio di risposta dell’assistant con `role`, `content` e, facoltativamente, `tool_calls`.
`choices[].finish_reason`	Il motivo per cui il model si è fermato: `stop`, `length`, `tool_calls` o `content_filter`.
`usage`	Dettaglio del consumo di token: `prompt_tokens`, `completion_tokens`, `total_tokens` e sottoconteggi dettagliati.
`system_fingerprint`	Fingerprint della configurazione backend per il debug della riproducibilità.

Note tra provider diversi

Supporto dei parametri tra provider

Parameter	OpenAI GPT	Claude (via compat)	Gemini (via compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	solo 1	1–8
`stop`	Fino a 4	Fino a 4	Fino a 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (usa `thinking` per Gemini native)

max_tokens vs max_completion_tokens

max_tokens — Il parametro legacy. Funziona con la maggior parte dei modelli ma è deprecato per i modelli OpenAI più recenti.
max_completion_tokens — Il parametro consigliato per i modelli GPT-4.1, serie GPT-5 e o-series. Obbligatorio per i modelli reasoning poiché include sia gli output tokens sia i reasoning tokens.

CometAPI gestisce automaticamente il mapping quando instrada verso provider diversi.

ruolo system vs developer

system — Il ruolo di istruzione tradizionale. Funziona con tutti i modelli.
developer — Introdotto con i modelli o1. Fornisce una maggiore aderenza alle istruzioni per i modelli più recenti. Sui modelli più vecchi ricade nel comportamento di system.

Usa developer per i nuovi progetti che puntano a GPT-4.1+ o ai modelli o-series.

FAQ

Come gestire i rate limit?

Quando incontri un errore 429 Too Many Requests, implementa un exponential backoff:

import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-5.4",
                messages=messages,
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

Come mantenere il contesto della conversazione?

Includi l’intera cronologia della conversazione nell’array messages:

messages = [
    {"role": "developer", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a high-level programming language..."},
    {"role": "user", "content": "What are its main advantages?"},
]

Cosa significa `finish_reason`?

Value	Meaning
`stop`	Completamento naturale oppure raggiungimento di una sequenza di stop.
`length`	Raggiunto il limite di `max_tokens` o `max_completion_tokens`.
`tool_calls`	Il modello ha invocato una o più chiamate tool/function.
`content_filter`	L’output è stato filtrato a causa della policy sui contenuti.

Come controllare i costi?

Usa max_completion_tokens per limitare la lunghezza dell’output.
Scegli modelli convenienti in termini di costo (ad es. gpt-5.4-mini o gpt-5.4-nano per attività più semplici).
Mantieni i prompt concisi — evita contesto ridondante.
Monitora l’utilizzo dei token nel campo usage della risposta.

Autorizzazioni

Authorization

string

header

obbligatorio

Bearer token authentication. Use your CometAPI key.

Corpo

application/json

model

string

predefinito:gpt-5.4

obbligatorio

Model ID to use for this request. See the Models page for current options.

Esempio:

"gpt-4.1"

messages

object[]

obbligatorio

A list of messages forming the conversation. Each message has a role (system, user, assistant, or developer) and content (text string or multimodal content array).

Show child attributes

stream

boolean

If true, partial response tokens are delivered incrementally via server-sent events (SSE). The stream ends with a data: [DONE] message.

temperature

number

predefinito:1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) produce more random output; lower values (e.g., 0.2) make output more focused and deterministic. Recommended to adjust this or top_p, but not both.

Intervallo richiesto: 0 <= x <= 2

top_p

number

predefinito:1

Nucleus sampling parameter. The model considers only the tokens whose cumulative probability reaches top_p. For example, 0.1 means only the top 10% probability tokens are considered. Recommended to adjust this or temperature, but not both.

Intervallo richiesto: 0 <= x <= 1

integer

predefinito:1

Number of completion choices to generate for each input message. Defaults to 1.

stop

string

Up to 4 sequences where the API will stop generating further tokens. Can be a string or an array of strings.

max_tokens

integer

Maximum number of tokens to generate in the completion. The total of input + output tokens is capped by the model's context length.

presence_penalty

number

predefinito:0

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared, encouraging the model to explore new topics.

Intervallo richiesto: -2 <= x <= 2

frequency_penalty

number

predefinito:0

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

Intervallo richiesto: -2 <= x <= 2

logit_bias

object

A JSON object mapping token IDs to bias values from -100 to 100. The bias is added to the model's logits before sampling. Values between -1 and 1 subtly adjust likelihood; -100 or 100 effectively ban or force selection of a token.

user

string

A unique identifier for your end-user. Helps with abuse detection and monitoring.

max_completion_tokens

integer

An upper bound for the number of tokens to generate, including visible output tokens and reasoning tokens. Use this instead of max_tokens for GPT-4.1+, GPT-5 series, and o-series models.

response_format

object

Specifies the output format. Use {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {...}} for strict structured output.

Show child attributes

tools

object[]

A list of tools the model may call. Currently supports function type tools.

Show child attributes

tool_choice

predefinito:auto

Controls how the model selects tools. auto (default): model decides. none: no tools. required: must call a tool.

logprobs

boolean

predefinito:false

Whether to return log probabilities of the output tokens.

top_logprobs

integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

Intervallo richiesto: 0 <= x <= 20

reasoning_effort

enum<string>

Controls the reasoning effort for o-series and GPT-5.1+ models.

Opzioni disponibili:

low,

medium,

high

stream_options

object

Options for streaming. Only valid when stream is true.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

Opzioni disponibili:

auto,

default,

flex,

priority

Risposta

200 - application/json

Successful chat completion response.

string

Unique completion identifier.

Esempio:

"chatcmpl-abc123"

object

enum<string>

Opzioni disponibili:

chat.completion

Esempio:

"chat.completion"

created

integer

Unix timestamp of creation.

Esempio:

1774412483

model

string

The model used (may include version suffix).

Esempio:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

Esempio:

"default"

system_fingerprint

string | null

Esempio:

"fp_490a4ad033"

Panoramica

Riferimento API

Guide all'integrazione

Errori

Prezzi e fatturazione

Supporto

Panoramica

Note importanti

Ruoli dei messaggi

Input Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Note tra provider diversi

FAQ

Come gestire i rate limit?

Come mantenere il contesto della conversazione?

Cosa significa `finish_reason`?

Come controllare i costi?

Autorizzazioni

Corpo

Risposta

Panoramica

Riferimento API

Guide all'integrazione

Errori

Prezzi e fatturazione

Supporto

​Panoramica

​Note importanti

​Ruoli dei messaggi

​Input Multimodal

​Streaming

​Structured Outputs

​Tool / Function Calling

​Response Fields

​Note tra provider diversi

​FAQ

​Come gestire i rate limit?

​Come mantenere il contesto della conversazione?

​Cosa significa finish_reason?

​Come controllare i costi?

Autorizzazioni

Corpo

Risposta

Panoramica

Note importanti

Ruoli dei messaggi

Input Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

Note tra provider diversi

FAQ

Come gestire i rate limit?

Come mantenere il contesto della conversazione?

Cosa significa `finish_reason`?

Come controllare i costi?