> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a chat completion

Invia una richiesta per una risposta del modello per la conversazione chat specificata. Supporta sia la modalità streaming che non-streaming. Compatibile con il formato dell'API OpenAI Chat Completions.

## Autenticazione

<ParamField header="Authorization" type="string" required>
  Token Bearer. Utilizza la tua chiave API come token Bearer nell'header Authorization.

  Format: `Bearer <SUNRA_KEY>`
</ParamField>

## Richiesta

Questo endpoint si aspetta un oggetto JSON.

<ParamField body="model" type="string" required>
  Il modello da utilizzare per il completamento. Sfoglia i modelli disponibili su [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="messages" type="object[]" required>
  Lista dei messaggi per la conversazione.

  <Expandable title="proprietà">
    <ParamField body="role" type="string" required>
      Il ruolo dell'autore del messaggio. Valori supportati: `system`, `user`, `assistant`.
    </ParamField>

    <ParamField body="content" type="string" required>
      Il contenuto del messaggio.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Se impostato su `true`, i delta parziali dei messaggi verranno inviati come Server-Sent Events (SSE).
</ParamField>

<ParamField body="max_tokens" type="integer">
  Il numero massimo di token da generare nel completamento.
</ParamField>

<ParamField body="temperature" type="number">
  Temperatura di campionamento tra 0 e 2. Valori più alti come 0.8 rendono l'output più casuale, valori più bassi come 0.2 lo rendono più focalizzato e deterministico.
</ParamField>

<ParamField body="top_p" type="number">
  Parametro di campionamento nucleus (0-1). Un'alternativa al campionamento per temperatura in cui il modello considera i token con massa di probabilità top\_p.
</ParamField>

<ParamField body="frequency_penalty" type="number">
  Numero tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base alla loro frequenza esistente nel testo finora, diminuendo la probabilità che il modello ripeta la stessa riga alla lettera.
</ParamField>

<ParamField body="presence_penalty" type="number">
  Numero tra -2.0 e 2.0. I valori positivi penalizzano i nuovi token in base alla loro presenza nel testo finora, aumentando la probabilità che il modello parli di nuovi argomenti.
</ParamField>

<ParamField body="stop" type="string | string[]">
  Fino a 4 sequenze in cui l'API smetterà di generare ulteriori token.
</ParamField>

## Risposta

Risposta di completamento chat riuscita.

<ResponseField name="id" type="string">
  Identificatore univoco del completamento.
</ResponseField>

<ResponseField name="object" type="string">
  Tipo di oggetto. Sempre `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  Timestamp Unix della creazione.
</ResponseField>

<ResponseField name="model" type="string">
  Modello utilizzato per il completamento.
</ResponseField>

<ResponseField name="choices" type="object[]">
  Lista delle opzioni di completamento.

  <Expandable title="proprietà">
    <ResponseField name="index" type="integer">
      Indice dell'opzione nella lista.
    </ResponseField>

    <ResponseField name="message" type="object">
      Il messaggio generato.

      <Expandable title="proprietà">
        <ResponseField name="role" type="string">
          Il ruolo dell'autore del messaggio. Sempre `assistant`.
        </ResponseField>

        <ResponseField name="content" type="string">
          Il contenuto del messaggio.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      Il motivo per cui il modello ha smesso di generare. Può essere `stop`, `length` o `content_filter`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Statistiche di utilizzo dei token.

  <Expandable title="proprietà">
    <ResponseField name="prompt_tokens" type="integer">
      Numero di token nel prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Numero di token nel completamento generato.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Numero totale di token utilizzati (prompt + completamento).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant."
        },
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/chat/completions",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "openai/gpt-4o",
          "messages": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "What is the capital of France?"}
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is the capital of France?" }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "openai/gpt-4o",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The capital of France is Paris."
        },
        "finish_reason": "stop"
      }
    ],
    "system_fingerprint": "fp_44709d6fcb",
    "usage": {
      "prompt_tokens": 25,
      "completion_tokens": 8,
      "total_tokens": 33
    }
  }
  ```
</ResponseExample>