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

Cria uma mensagem usando o formato da API Anthropic Messages. Suporta texto, imagens, PDFs, ferramentas e pensamento estendido.

## 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="model" type="string" required>
  O modelo que completará seu prompt. Navegue pelos modelos disponíveis em [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="messages" type="object[]" required>
  Mensagens de entrada. Cada mensagem de entrada tem um `role` e `content`.

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

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

      <Expandable title="tipos de blocos de conteúdo">
        <ParamField body="type" type="string" required>
          O tipo de bloco de conteúdo. Valores suportados: `text`, `image`, `tool_use`, `tool_result`.
        </ParamField>

        <ParamField body="text" type="string">
          Conteúdo de texto. Usado quando o tipo é `text`.
        </ParamField>

        <ParamField body="source" type="object">
          Fonte da imagem. Usado quando o tipo é `image`.

          <Expandable title="propriedades">
            <ParamField body="type" type="string" required>
              O tipo de fonte. Valores suportados: `base64`, `url`.
            </ParamField>

            <ParamField body="media_type" type="string" required>
              O tipo de mídia da imagem. Por exemplo, `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
            </ParamField>

            <ParamField body="data" type="string">
              Dados de imagem codificados em base64. Obrigatório quando o tipo de fonte é `base64`.
            </ParamField>

            <ParamField body="url" type="string">
              URL da imagem. Obrigatório quando o tipo de fonte é `url`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  O número máximo de tokens a gerar antes de parar. Note que o modelo pode parar antes de atingir este máximo.
</ParamField>

<ParamField body="system" type="string | object[]">
  Prompt do sistema. Um prompt do sistema é uma forma de fornecer contexto e instruções ao modelo. Pode ser uma string ou um array de blocos de conteúdo.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Indica se a resposta deve ser transmitida de forma incremental usando eventos server-sent (SSE).
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  Quantidade de aleatoriedade injetada na resposta. Varia de 0.0 a 1.0. Use `temperature` mais próxima de 0.0 para tarefas analíticas/de múltipla escolha, e mais próxima de 1.0 para tarefas criativas e generativas.
</ParamField>

<ParamField body="top_p" type="number">
  Usa amostragem por núcleo. Na amostragem por núcleo, calculamos a distribuição cumulativa sobre todas as opções para cada token seguinte em ordem decrescente de probabilidade e a cortamos quando atinge uma probabilidade particular especificada por `top_p`.
</ParamField>

<ParamField body="top_k" type="integer">
  Amostra apenas entre as K melhores opções para cada token seguinte. Usado para remover respostas de baixa probabilidade da "cauda longa". Recomendado apenas para casos de uso avançados.
</ParamField>

<ParamField body="stop_sequences" type="string[]">
  Sequências de texto personalizadas que farão o modelo parar de gerar. O texto retornado não conterá a sequência de parada.
</ParamField>

<ParamField body="tools" type="object[]">
  Definições de ferramentas que o modelo pode usar.

  <Expandable title="propriedades">
    <ParamField body="name" type="string" required>
      Nome da ferramenta.
    </ParamField>

    <ParamField body="description" type="string">
      Descrição do que esta ferramenta faz.
    </ParamField>

    <ParamField body="input_schema" type="object" required>
      Esquema JSON para a entrada desta ferramenta. Isso define a forma do `input` que sua ferramenta aceita.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="object">
  Como o modelo deve usar as ferramentas fornecidas.

  <Expandable title="propriedades">
    <ParamField body="type" type="string" required>
      Valores suportados: `auto` (padrão, o modelo decide), `any` (o modelo deve usar uma ferramenta), `tool` (o modelo deve usar uma ferramenta específica).
    </ParamField>

    <ParamField body="name" type="string">
      O nome da ferramenta a usar. Obrigatório quando o tipo é `tool`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Um objeto descrevendo os metadados da requisição.

  <Expandable title="propriedades">
    <ParamField body="user_id" type="string">
      Um identificador externo para o usuário associado à requisição.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="thinking" type="object">
  Configuração para o pensamento estendido. Quando habilitado, o modelo pensará antes de responder.

  <Expandable title="propriedades">
    <ParamField body="type" type="string" required>
      Deve ser `enabled`.
    </ParamField>

    <ParamField body="budget_tokens" type="integer" required>
      O número máximo de tokens a usar para o pensamento. Deve ser maior ou igual a 1024.
    </ParamField>
  </Expandable>
</ParamField>

## Resposta

Resposta de mensagem bem-sucedida.

<ResponseField name="id" type="string">
  Identificador único da mensagem, por exemplo `msg_01XFDUDYJgAACzvnptvVoYEL`.
</ResponseField>

<ResponseField name="type" type="string">
  Tipo de objeto. Sempre `message`.
</ResponseField>

<ResponseField name="role" type="string">
  Papel conversacional da mensagem gerada. Sempre `assistant`.
</ResponseField>

<ResponseField name="content" type="object[]">
  Conteúdo gerado pelo modelo. Este é um array de blocos de conteúdo.

  <Expandable title="propriedades">
    <ResponseField name="type" type="string">
      O tipo de bloco de conteúdo. Pode ser `text`, `tool_use` ou `thinking`.
    </ResponseField>

    <ResponseField name="text" type="string">
      O texto gerado. Presente quando o tipo é `text`.
    </ResponseField>

    <ResponseField name="id" type="string">
      O ID do bloco de uso de ferramenta. Presente quando o tipo é `tool_use`.
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome da ferramenta. Presente quando o tipo é `tool_use`.
    </ResponseField>

    <ResponseField name="input" type="object">
      A entrada da ferramenta. Presente quando o tipo é `tool_use`.
    </ResponseField>

    <ResponseField name="thinking" type="string">
      O conteúdo do pensamento. Presente quando o tipo é `thinking`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  O modelo que processou a requisição.
</ResponseField>

<ResponseField name="stop_reason" type="string | null">
  A razão pela qual o modelo parou de gerar. Pode ser `end_turn` (o modelo atingiu um ponto de parada natural), `max_tokens` (excedeu `max_tokens` ou o máximo do modelo), `stop_sequence` (uma de suas sequências de parada personalizadas foi gerada) ou `tool_use` (o modelo invocou uma ou mais ferramentas).
</ResponseField>

<ResponseField name="stop_sequence" type="string | null">
  Qual sequência de parada personalizada foi gerada, se alguma.
</ResponseField>

<ResponseField name="usage" type="object">
  Uso para faturamento e limites de taxa. Os três buckets de entrada são mutuamente exclusivos — veja [Uso de tokens](/pt/llm/token-usage).

  <Expandable title="propriedades">
    <ResponseField name="input_tokens" type="integer">
      O número de tokens de entrada novos utilizados. Exclui ambos os buckets de cache.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      O número de tokens de saída utilizados.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Todos os buckets de entrada mais `output_tokens`. Omitido em respostas com streaming.
    </ResponseField>

    <ResponseField name="cache_creation_input_tokens" type="integer">
      O número de tokens de entrada usados para criar a entrada de cache.
    </ResponseField>

    <ResponseField name="cache_read_input_tokens" type="integer">
      O número de tokens de entrada lidos do cache.
    </ResponseField>

    <ResponseField name="sunra_usage_semantics" type="string | null">
      Presente como `anthropic.exclusive.v1` quando Sunra normalizou esta resposta. Verifique este valor em vez de inferir a convenção a partir dos números. Veja [Uso de tokens](/pt/llm/token-usage).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/messages \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-sonnet-4-20250514",
      "max_tokens": 1024,
      "messages": [
        {
          "role": "user",
          "content": "Hello, how are you?"
        }
      ]
    }'
  ```

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

  response = requests.post(
      "https://api-llm.sunra.ai/v1/messages",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "anthropic/claude-sonnet-4-20250514",
          "max_tokens": 1024,
          "messages": [
              {"role": "user", "content": "Hello, how are you?"}
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "anthropic/claude-sonnet-4-20250514",
      max_tokens: 1024,
      messages: [
        { role: "user", content: "Hello, how are you?" }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ],
    "model": "anthropic/claude-sonnet-4-20250514",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 12,
      "output_tokens": 19,
      "total_tokens": 31,
      "sunra_usage_semantics": "anthropic.exclusive.v1"
    }
  }
  ```
</ResponseExample>