> ## 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

Envia uma requisição para obter uma resposta do modelo para a conversa de chat fornecida. Suporta modos streaming e não-streaming. Compatível com o formato da API OpenAI Chat Completions.

## Autenticação

<ParamField header="Authorization" type="string" required>
  Token Bearer. Use sua chave de API como token Bearer no cabeçalho Authorization.

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

## Requisição

Este endpoint espera um objeto.

<ParamField body="messages" type="object[]" required>
  Lista de mensagens para a conversa.

  <Expandable title="propriedades">
    <ParamField body="role" type="string" required>
      O papel do autor da mensagem. Valores suportados: `system`, `user`, `assistant`, `tool`.
    </ParamField>

    <ParamField body="content" type="string | object[]" required>
      O conteúdo da mensagem. Pode ser uma string ou um array de partes de conteúdo para entrada multimodal.
    </ParamField>

    <ParamField body="name" type="string">
      Um nome opcional para o participante. Fornece ao modelo informações para diferenciar entre participantes com o mesmo papel.
    </ParamField>

    <ParamField body="tool_calls" type="object[]">
      As chamadas de ferramentas geradas pelo modelo, como chamadas de funções. Presente apenas em mensagens `assistant`.
    </ParamField>

    <ParamField body="tool_call_id" type="string">
      A chamada de ferramenta à qual esta mensagem está respondendo. Presente apenas em mensagens `tool`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="model" type="string" required>
  O modelo a ser usado para a completação. Navegue pelos modelos disponíveis em [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Se definido como `true`, deltas de mensagens parciais serão enviados como eventos server-sent (SSE).
</ParamField>

<ParamField body="max_tokens" type="integer">
  O número máximo de tokens a gerar na completação. O comprimento total dos tokens de entrada e tokens gerados é limitado pelo comprimento de contexto do modelo.
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  Temperatura de amostragem entre 0 e 2. Valores mais altos como 0.8 tornam a saída mais aleatória, valores mais baixos como 0.2 a tornam mais focada e determinística.
</ParamField>

<ParamField body="top_p" type="number" default={1}>
  Parâmetro de amostragem por núcleo (0-1). Uma alternativa à amostragem por temperatura onde o modelo considera os tokens com massa de probabilidade top\_p.
</ParamField>

<ParamField body="frequency_penalty" type="number" default={0}>
  Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base na sua frequência existente no texto até o momento, diminuindo a probabilidade do modelo repetir a mesma linha literalmente.
</ParamField>

<ParamField body="presence_penalty" type="number" default={0}>
  Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em se eles aparecem no texto até o momento, aumentando a probabilidade do modelo falar sobre novos tópicos.
</ParamField>

<ParamField body="stop" type="string | string[]">
  Até 4 sequências onde a API deixará de gerar tokens adicionais.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  Quantas opções de completação de chat gerar para cada mensagem de entrada.
</ParamField>

<ParamField body="logprobs" type="boolean" default={false}>
  Indica se devem ser retornadas as log-probabilidades dos tokens de saída. Se verdadeiro, retorna as log-probabilidades de cada token de saída retornado no conteúdo da mensagem.
</ParamField>

<ParamField body="top_logprobs" type="integer">
  Um inteiro entre 0 e 20 especificando o número de tokens mais prováveis a retornar em cada posição de token. `logprobs` deve estar definido como `true` se este parâmetro for usado.
</ParamField>

<ParamField body="response_format" type="object">
  Um objeto especificando o formato que o modelo deve produzir.

  <Expandable title="propriedades">
    <ParamField body="type" type="string" required>
      O tipo de formato de resposta. Valores suportados: `text`, `json_object`, `json_schema`.
    </ParamField>

    <ParamField body="json_schema" type="object">
      O objeto de esquema JSON. Obrigatório quando o tipo é `json_schema`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="seed" type="integer">
  Se especificado, o sistema fará um esforço otimizado para amostrar de forma determinística, de modo que requisições repetidas com o mesmo seed e parâmetros devem retornar o mesmo resultado.
</ParamField>

<ParamField body="tools" type="object[]">
  Uma lista de ferramentas que o modelo pode chamar. Atualmente, apenas funções são suportadas como ferramenta.

  <Expandable title="propriedades">
    <ParamField body="type" type="string" required>
      O tipo da ferramenta. Atualmente, apenas `function` é suportado.
    </ParamField>

    <ParamField body="function" type="object" required>
      A definição da função.

      <Expandable title="propriedades">
        <ParamField body="name" type="string" required>
          O nome da função a ser chamada.
        </ParamField>

        <ParamField body="description" type="string">
          Uma descrição do que a função faz.
        </ParamField>

        <ParamField body="parameters" type="object">
          Os parâmetros que a função aceita, descritos como um objeto JSON Schema.
        </ParamField>

        <ParamField body="strict" type="boolean" default={false}>
          Indica se deve habilitar a aderência estrita ao esquema.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controla qual ferramenta (se alguma) é chamada pelo modelo. `none` significa que o modelo não chamará nenhuma ferramenta. `auto` significa que o modelo pode escolher entre gerar uma mensagem ou chamar ferramentas. `required` significa que o modelo deve chamar uma ou mais ferramentas. Também pode especificar uma função particular via `{"type": "function", "function": {"name": "my_function"}}`.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default={true}>
  Indica se deve habilitar a chamada de funções em paralelo durante o uso de ferramentas.
</ParamField>

<ParamField body="user" type="string">
  Um identificador único representando seu usuário final, que pode ajudar a monitorar e detectar abusos.
</ParamField>

## Resposta

Resposta de completação de chat bem-sucedida.

<ResponseField name="id" type="string">
  Um identificador único para a completação de chat.
</ResponseField>

<ResponseField name="object" type="string">
  O tipo de objeto. Sempre `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  A marca temporal Unix (em segundos) de quando a completação de chat foi criada.
</ResponseField>

<ResponseField name="model" type="string">
  O modelo usado para a completação de chat.
</ResponseField>

<ResponseField name="choices" type="object[]">
  Uma lista de opções de completação de chat. Pode conter mais de uma se `n` for maior que 1.

  <Expandable title="propriedades">
    <ResponseField name="index" type="integer">
      O índice da opção na lista de opções.
    </ResponseField>

    <ResponseField name="message" type="object">
      Uma mensagem de completação de chat gerada pelo modelo.

      <Expandable title="propriedades">
        <ResponseField name="role" type="string">
          O papel do autor desta mensagem. Sempre `assistant`.
        </ResponseField>

        <ResponseField name="content" type="string | null">
          O conteúdo da mensagem.
        </ResponseField>

        <ResponseField name="tool_calls" type="object[]">
          As chamadas de ferramentas geradas pelo modelo, como chamadas de funções.

          <Expandable title="propriedades">
            <ResponseField name="id" type="string">
              O ID da chamada de ferramenta.
            </ResponseField>

            <ResponseField name="type" type="string">
              O tipo da ferramenta. Atualmente, apenas `function` é suportado.
            </ResponseField>

            <ResponseField name="function" type="object">
              A função que o modelo chamou.

              <Expandable title="propriedades">
                <ResponseField name="name" type="string">
                  O nome da função a chamar.
                </ResponseField>

                <ResponseField name="arguments" type="string">
                  Os argumentos para chamar a função, gerados pelo modelo em formato JSON.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      A razão pela qual o modelo parou de gerar tokens. Pode ser `stop`, `length`, `tool_calls` ou `content_filter`.
    </ResponseField>

    <ResponseField name="logprobs" type="object | null">
      Informações de log-probabilidade para a opção.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Estatísticas de uso para a requisição de completação.

  <Expandable title="propriedades">
    <ResponseField name="prompt_tokens" type="integer">
      Número de tokens no prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Número de tokens na completação gerada.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Número total de tokens utilizados na requisição (prompt + completação).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="system_fingerprint" type="string | null">
  Esta impressão digital representa a configuração do backend com a qual o modelo é executado. Pode ser usada com o parâmetro `seed` para entender quando mudanças no backend foram feitas.
</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",
        "logprobs": null
      }
    ],
    "system_fingerprint": "fp_44709d6fcb",
    "usage": {
      "prompt_tokens": 25,
      "completion_tokens": 8,
      "total_tokens": 33
    }
  }
  ```
</ResponseExample>