Chat Completions

Gere respostas conversacionais com a API de Chat Completions da Polar, compatível com OpenAI.

Visão Geral

O endpoint POST /v1/chat/completions é o principal ponto de entrada da API Polar. Ele aceita uma lista de mensagens representando uma conversa e retorna a resposta do modelo. A API é totalmente compatível com o formato OpenAI, permitindo migração com uma única linha de código.

Endpoint

POST https://api.polar-ai.com/v1/chat/completions

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`model`	string	Sim	—	Modelo a ser usado (`urso-lite`, `urso-base`, `urso-pro`, `urso-ultra`)
`messages`	array	Sim	—	Lista de mensagens da conversa
`temperature`	number	Não	0.7	Controla aleatoriedade (0.0 a 2.0)
`top_p`	number	Não	1.0	Nucleus sampling (0.0 a 1.0)
`max_tokens`	integer	Não	4096	Número máximo de tokens na resposta
`stream`	boolean	Não	false	Habilita streaming via SSE
`stop`	string/array	Não	null	Sequências que interrompem a geração
`presence_penalty`	number	Não	0.0	Penalidade por presença (-2.0 a 2.0)
`frequency_penalty`	number	Não	0.0	Penalidade por frequência (-2.0 a 2.0)
`tools`	array	Não	null	Lista de ferramentas/funções disponíveis
`response_format`	object	Não	null	Formato de resposta (`text`, `json_object`, `json_schema`)
`seed`	integer	Não	null	Semente para reproducibilidade
`user`	string	Não	null	Identificador do usuário final

Formato de Mensagens

Cada mensagem possui um role e um content:

Role	Descrição
`system`	Instruções de comportamento para o modelo
`user`	Mensagem do usuário
`assistant`	Resposta do modelo
`tool`	Resultado de uma chamada de ferramenta

Mensagem do Sistema

O system prompt define o comportamento e personalidade do modelo:

{
  "role": "system",
  "content": "Você é um assistente jurídico especializado em direito brasileiro. Responda sempre citando a legislação aplicável."
}

Mensagem do Usuário

{
  "role": "user",
  "content": "Quais são os direitos do consumidor em caso de produto com defeito?"
}

Mensagem do Assistente

Usada para fornecer contexto de respostas anteriores em conversas multi-turno:

{
  "role": "assistant",
  "content": "De acordo com o Código de Defesa do Consumidor (Lei 8.078/90)..."
}

Exemplo Básico

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

response = client.chat.completions.create(
    model="urso-base",
    messages=[
        {
            "role": "system",
            "content": "Você é um assistente prestativo que responde em português brasileiro."
        },
        {
            "role": "user",
            "content": "Explique o que é a LGPD de forma simples."
        }
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.polar-ai.com/v1",
  apiKey: "pk-your-key-here",
});

const response = await client.chat.completions.create({
  model: "urso-base",
  messages: [
    {
      role: "system",
      content: "Você é um assistente prestativo que responde em português brasileiro.",
    },
    {
      role: "user",
      content: "Explique o que é a LGPD de forma simples.",
    },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(response.choices[0].message.content);

curl

curl -X POST https://api.polar-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk-your-key-here" \
  -d '{
    "model": "urso-base",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente prestativo que responde em português brasileiro."
      },
      {
        "role": "user",
        "content": "Explique o que é a LGPD de forma simples."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Conversa Multi-turno

Para manter contexto entre mensagens, envie o histórico completo da conversa:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

messages = [
    {"role": "system", "content": "Você é um advogado especialista em direito trabalhista brasileiro."},
    {"role": "user", "content": "Qual o prazo para entrar com uma ação trabalhista?"},
]

# Primeira resposta
response = client.chat.completions.create(
    model="urso-pro",
    messages=messages
)

assistant_message = response.choices[0].message.content
messages.append({"role": "assistant", "content": assistant_message})

# Continuar a conversa
messages.append({"role": "user", "content": "E se o trabalhador foi demitido por justa causa?"})

response = client.chat.completions.create(
    model="urso-pro",
    messages=messages
)

print(response.choices[0].message.content)

Formato da Resposta

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "urso-base",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A LGPD (Lei Geral de Proteção de Dados) é a lei brasileira que regulamenta..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  }
}

Parâmetros Avançados

Controle de Temperatura

temperature=0.0: Respostas determinísticas, ideais para tarefas analíticas
temperature=0.3-0.7: Equilíbrio entre criatividade e coerência
temperature=1.0-2.0: Respostas mais criativas e diversas

Penalidades

presence_penalty: Valores positivos incentivam o modelo a falar sobre novos tópicos
frequency_penalty: Valores positivos reduzem a repetição de palavras

Seed para Reproducibilidade

Passe um valor seed para obter respostas mais consistentes entre chamadas:

response = client.chat.completions.create(
    model="urso-base",
    messages=[{"role": "user", "content": "Conte uma piada."}],
    seed=42,
    temperature=0.5
)

Próximos Passos

Streaming — receba respostas em tempo real
Function Calling — integre ferramentas externas
Structured Output — obtenha JSON estruturado
Vision — envie imagens junto com texto

On this page