Crea un completamento della chat

POST

chat

completions

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Invia conversazioni tramite l’API Chat Completions compatibile con OpenAI. Configura il tuo SDK con base_url="https://api.cometapi.com/v1" e la tua chiave API CometAPI. Gli esempi di base, relativi alle immagini, di Streaming e di output strutturato usano gpt-6-astra. L’esempio di function calling usa gpt-5.6-sol, mentre l’esempio di probabilità logaritmica usa gpt-4.1.

Usa il riferimento OpenAI Chat Completions per le definizioni dei parametri. Per il tool calling Astra di GPT-6, usa Responses, seguendo le indicazioni sui modelli di OpenAI.

Ruoli dei messaggi

Ruolo	Descrizione
`system`	Definisce il comportamento e la personalità dell’assistente. Viene inserito all’inizio della conversazione.
`developer`	Fornisce istruzioni per l’applicazione. Gli esempi Astra di GPT-6 usano questo ruolo.
`user`	Messaggi dell’utente finale.
`assistant`	Risposte precedenti del modello, usate per mantenere la cronologia della conversazione.
`tool`	Risultati delle chiamate di strumenti/funzioni. Deve includere `tool_call_id` corrispondente alla chiamata di strumento originale.

Inserisci le istruzioni dell’applicazione in un messaggio developer prima dei messaggi utente quando usi gli esempi Astra di GPT-6.

Invia input Multimodal

Usa un array di parti di contenuto per inviare un’immagine con del testo:

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe the road and surrounding landscape in this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=1200",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "reasoning_effort": "low",
  "max_completion_tokens": 4096
}

Usa image_url.detail per selezionare il livello di dettaglio dell’elaborazione delle immagini. Questo esempio usa high.

Risposte in streaming

Per ricevere output incrementale, imposta stream su true. La risposta viene fornita come eventi inviati dal server (SSE)). Il testo arriva in oggetti chat.completion.chunk; questo esempio abbreviato include il chunk di utilizzo finale:

data: {"choices":[{"delta":{"content":"","refusal":null,"role":"assistant"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[{"delta":{"content":"Hi"},"finish_reason":null,"index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

: Additional text deltas omitted

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0,"logprobs":null}],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk"}

data: {"choices":[],"created":1788765075,"id":"chatcmpl_example","model":"gpt-6-astra-2026-09-03","object":"chat.completion.chunk","usage":{"completion_tokens":12,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens":18,"prompt_tokens_details":{"audio_tokens":0,"cache_write_tokens":0,"cached_tokens":0},"total_tokens":30}}

data: [DONE]

Per includere statistiche sull’utilizzo dei token nelle risposte in streaming, imposta stream_options.include_usage su true. I dati di utilizzo vengono visualizzati in un chunk finale prima di [DONE]. I chunk possono avere un array choices vuoto; controllalo prima di accedere a choices[0].

Richiedere output strutturato

Usa response_format per richiedere output strutturato:

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France? Return the answer and your confidence as a number from 0 to 1."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "The answer to the question."
          },
          "confidence": {
            "type": "number",
            "description": "Confidence between zero and one."
          }
        },
        "required": [
          "answer",
          "confidence"
        ],
        "additionalProperties": false
      }
    }
  }
}

{
  "model": "gpt-6-astra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with the key answer and the capital of France as its value."
    }
  ],
  "reasoning_effort": "low",
  "response_format": {
    "type": "json_object"
  }
}

La modalità JSON Schema specifica la struttura richiesta. La modalità JSON Object richiede JSON valido senza imporre il tuo schema. Verifica la presenza di un rifiuto o di una risposta limitata in lunghezza prima di utilizzare il risultato.

Chiamare strumenti e funzioni

Usa gpt-5.6-sol con una definizione di funzione:

{
  "model": "gpt-5.6-sol",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in Boston, MA, in celsius? Use the weather tool."
    }
  ],
  "reasoning_effort": "none",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and state, for example Boston, MA."
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ],
              "description": "Temperature unit."
            }
          },
          "required": [
            "location",
            "unit"
          ],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}

Una chiamata di funzione restituisce finish_reason: "tool_calls" e un array message.tool_calls. Analizza arguments della funzione, codificato in JSON, esegui la funzione, quindi aggiungi il messaggio dell’assistente e un messaggio di risultato tool con il relativo tool_call_id.

Scegliere i parametri della richiesta

Parametri specifici del modello

Usa reasoning_effort e max_completion_tokens con Astra GPT-6. Gli esempi Functions e Logprobs mostrano le opzioni di richiesta rispettivamente per gpt-5.6-sol e gpt-4.1.Per i formati di richiesta specifici di Claude o Gemini, consulta Anthropic Messages e Gemini Generate content.

max_tokens e max_completion_tokens

Usa max_completion_tokens per limitare i Tokens generati negli esempi Astra GPT-6. Questo include il ragionamento e l’output visibile, quindi lascia spazio per entrambi. max_tokens è un parametro legacy.

Ruoli delle istruzioni

Usa developer per le istruzioni dell’applicazione negli esempi Astra GPT-6. Mantieni i contenuti dell’utente finale nei messaggi user e conserva le risposte precedenti dell’assistente quando prosegui una conversazione.

Domande frequenti

Come gestire i limiti di frequenza?

Quando si verifica 429 Too Many Requests, implementa un backoff esponenziale:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-6-astra",
                messages=messages,
                reasoning_effort="low",
            )
        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 `finish_reason` significa?

Valore	Significato
`stop`	Completamento naturale o raggiungimento di una sequenza di arresto.
`length`	È stato raggiunto il limite di `max_tokens` o `max_completion_tokens`.
`tool_calls`	Il modello ha invocato una o più chiamate di strumenti/funzioni.
`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.
Confronta i prezzi dei modelli e scegli un modello che soddisfi i requisiti del tuo carico di lavoro.
Mantieni i prompt concisi: evita il contesto ridondante.
Monitora l’utilizzo dei token nel campo di risposta usage.

Autorizzazioni

Authorization

string

header

obbligatorio

Bearer token authentication. Use your CometAPI key.

Corpo

application/json

model

string

predefinito:gpt-6-astra

obbligatorio

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

Esempio:

"gpt-6-astra"

messages

object[]

obbligatorio

Conversation messages, including instructions, user input, assistant replies, and tool results.

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

Sampling temperature. Omit this field for GPT-6 Astra.

Intervallo richiesto: 0 <= x <= 2

top_p

number

Nucleus sampling threshold. Omit this field for GPT-6 Astra. For sampling overrides, adjust either top_p or temperature.

Intervallo richiesto: 0 <= x <= 1

integer

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

stop

Stop string or list of up to four strings, for models that support stop sequences.

max_tokens

integer

deprecato

Legacy output-token limit. Use max_completion_tokens for the GPT-6 Astra examples.

presence_penalty

number

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

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

Maximum generated tokens, including visible output and reasoning. Leave enough room for both, as in the image-input example.

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[]

Function definitions for a model that supports tool calling on Chat Completions. The function example uses GPT-5.6 Sol; use Responses for GPT-6 Astra tool calls.

Show child attributes

tool_choice

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

logprobs

boolean

Return token log probabilities. Use gpt-4.1 as shown in the Logprobs example.

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

string

Reasoning effort supported by the selected model. The GPT-6 Astra examples use low; the GPT-5.6 Sol function example uses none. See the model reference for other supported levels.

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

Successful chat completion response.

string

Unique completion identifier.

Esempio:

"chatcmpl_example"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

Opzioni disponibili:

chat.completion

Esempio:

"chat.completion"

created

integer

Unix timestamp of creation.

Esempio:

1788763703

model

string

The model used (may include version suffix).

Esempio:

"gpt-6-astra"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when returned.

system_fingerprint

string | null

Model configuration fingerprint, when returned.

Ultima modifica il 8 settembre 2026

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant.",
        },
        {
            "role": "user",
            "content": "Hello!",
        },
    ],
    reasoning_effort="low",
)

print(completion.choices[0].message)

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "annotations": [],
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "role": "assistant"
      }
    }
  ],
  "created": 1788763703,
  "id": "chatcmpl_example",
  "model": "gpt-6-astra",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens": 18,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "total_tokens": 30
  }
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Moderazione dei contenuti

Chiavi API

Ruoli dei messaggi

Invia input Multimodal

Risposte in streaming

Richiedere output strutturato

Chiamare strumenti e funzioni

Scegliere i parametri della richiesta

Domande frequenti

Come gestire i limiti di frequenza?

Come mantenere il contesto della conversazione?

Cosa `finish_reason` significa?

Come controllare i costi?

Autorizzazioni

Corpo

Risposta

​Ruoli dei messaggi

​Invia input Multimodal

​Risposte in streaming

​Richiedere output strutturato

​Chiamare strumenti e funzioni

​Scegliere i parametri della richiesta

​Domande frequenti

​Come gestire i limiti di frequenza?

​Come mantenere il contesto della conversazione?

​Cosa finish_reason significa?

​Come controllare i costi?

Autorizzazioni

Corpo

Risposta

Ruoli dei messaggi

Invia input Multimodal

Risposte in streaming

Richiedere output strutturato

Chiamare strumenti e funzioni

Scegliere i parametri della richiesta

Domande frequenti

Come gestire i limiti di frequenza?

Come mantenere il contesto della conversazione?

Cosa `finish_reason` significa?

Come controllare i costi?