Criar uma conclusão de 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-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "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"
  }
}

O CometAPI direciona Chat Completions para vários provedores — incluindo OpenAI, Claude e Gemini — por meio de uma única interface compatível com OpenAI. Alterne entre modelos mudando o parâmetro model; a maioria dos SDKs compatíveis com OpenAI funciona ao definir base_url como https://api.cometapi.com/v1.

Os parâmetros de solicitação e os campos de resposta podem variar significativamente entre provedores de modelos. Consulte a documentação oficial do provedor por trás do modelo que você usa sempre que precisar da lista completa de parâmetros ou de comportamentos específicos do provedor. Por exemplo, reasoning_effort aplica-se apenas a modelos de raciocínio (o-series, GPT-5.1+), e alguns modelos não oferecem suporte a logprobs ou n > 1.

Para modelos OpenAI Pro, modelos de raciocínio o-series e modelos Codex, use o Responses endpoint. Essas famílias de modelos têm suporte mais completo na API Responses.

Funções das mensagens

Função	Descrição
`system`	Define o comportamento e a personalidade do assistente. É colocada no início da conversa.
`developer`	Substitui `system` em modelos mais recentes (o1+). Fornece instruções que o modelo deve seguir independentemente da entrada do usuário.
`user`	Mensagens do usuário final.
`assistant`	Respostas anteriores do modelo, usadas para manter o histórico da conversa.
`tool`	Resultados de chamadas de ferramentas/funções. Deve incluir `tool_call_id` correspondente à chamada de ferramenta original.

Para modelos mais recentes (GPT-4.1, série GPT-5, o-series), prefira developer a system para mensagens de instrução. Ambos funcionam, mas developer proporciona um comportamento mais forte de seguimento de instruções.

Enviar entrada multimodal

Muitos modelos oferecem suporte a imagens e áudio juntamente com texto. Para enviar mensagens Multimodal, use o formato de matriz para content:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this image"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    }
  ]
}

O parâmetro detail controla a profundidade da análise de imagens:

low — mais rápido, usa menos tokens (custo fixo)
high — análise detalhada, consome mais tokens
auto — o modelo decide (padrão)

Transmitir respostas

Para receber saída incremental, defina stream como true. A resposta é entregue como Eventos enviados pelo servidor (SSE), em que cada evento contém um objeto chat.completion.chunk:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Para incluir estatísticas de uso de tokens nas respostas transmitidas, defina stream_options.include_usage como true. Os dados de uso aparecem no bloco final antes de [DONE].

Solicitar saída estruturada

Para forçar o modelo a retornar JSON válido correspondente a um esquema específico, use response_format:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        },
        "required": ["answer", "confidence"],
        "additionalProperties": false
      }
    }
  }
}

{
  "response_format": {"type": "json_object"}
}

O modo JSON Schema (json_schema) garante que a saída corresponda exatamente ao seu esquema. O modo JSON Object (json_object) garante apenas JSON válido — a estrutura não é imposta.

Chamar ferramentas e funções

Para permitir que o modelo chame funções externas, forneça definições de ferramentas:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Quando o modelo decidir chamar uma ferramenta, a resposta terá finish_reason: "tool_calls" e a matriz message.tool_calls conterá o nome e os argumentos da função. Em seguida, execute a função e envie o resultado de volta como uma mensagem tool com o tool_call_id correspondente.

Observações entre provedores

Suporte a parâmetros entre provedores

Parâmetro	OpenAI GPT	Claude (via compat)	Gemini (via compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	Apenas 1	1–8
`stop`	Até 4	Até 4	Até 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series, GPT-5.1+	❌	❌ (use `thinking` para Gemini nativo)

max_tokens vs max_completion_tokens

max_tokens — O parâmetro legado. Funciona com a maioria dos modelos, mas está obsoleto para modelos OpenAI mais recentes.
max_completion_tokens — O parâmetro recomendado para modelos GPT-4.1, da série GPT-5 e o-series. Obrigatório para modelos de raciocínio, pois inclui tokens de saída e tokens de raciocínio.

O CometAPI processa automaticamente o mapeamento ao direcionar para diferentes provedores.

função system vs developer

system — A função de instrução tradicional. Funciona com todos os modelos.
developer — Introduzida com os modelos o1. Oferece um seguimento de instruções mais forte para modelos mais recentes. Usa o comportamento de system como alternativa em modelos mais antigos.

Use developer em novos projetos destinados a modelos GPT-4.1+ ou o-series.

Perguntas frequentes

Como lidar com limites de taxa?

Ao encontrar 429 Too Many Requests, implemente backoff exponencial:

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-5.6-sol",
                messages=messages,
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

Como manter o contexto da conversa?

Inclua todo o histórico da conversa na matriz 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?"},
]

O que `finish_reason` querdizer?

Valor	Significado
`stop`	Conclusão natural ou atingiu uma sequência de parada.
`length`	Atingiu o limite de `max_tokens` ou `max_completion_tokens`.
`tool_calls`	O modelo invocou uma ou mais chamadas de ferramentas/funções.
`content_filter`	A saída foi filtrada devido à política de conteúdo.

Como controlar os custos?

Use max_completion_tokens para limitar o comprimento da saída.
Use gpt-5.6-terra para equilibrar inteligência e custo, ou gpt-5.6-luna para cargas de trabalho eficientes e de alto volume.
Mantenha os prompts concisos — evite contexto redundante.
Monitore o uso de tokens no campo de resposta usage.

Autorizações

Authorization

string

header

obrigatório

Bearer token authentication. Use your CometAPI key.

Corpo

application/json

model

string

padrão:gpt-5.6-sol

obrigatório

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

Exemplo:

"gpt-4.1"

messages

object[]

obrigatório

A list of messages forming the conversation. Each message has a role (system, user, assistant, or developer) and content (text string or multimodal content array).

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

padrão:1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) produce more random output; lower values (e.g., 0.2) make output more focused and deterministic. Recommended to adjust this or top_p, but not both.

Intervalo necessário: 0 <= x <= 2

top_p

number

padrão:1

Nucleus sampling parameter. The model considers only the tokens whose cumulative probability reaches top_p. For example, 0.1 means only the top 10% probability tokens are considered. Recommended to adjust this or temperature, but not both.

Intervalo necessário: 0 <= x <= 1

integer

padrão:1

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

stop

string

Up to 4 sequences where the API will stop generating further tokens. Can be a string or an array of strings.

max_tokens

integer

Maximum number of tokens to generate in the completion. The total of input + output tokens is capped by the model's context length.

presence_penalty

number

padrão:0

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.

Intervalo necessário: -2 <= x <= 2

frequency_penalty

number

padrão:0

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

Intervalo necessário: -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

An upper bound for the number of tokens to generate, including visible output tokens and reasoning tokens. Use this instead of max_tokens for GPT-4.1+, GPT-5 series, and o-series models.

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

A list of tools the model may call. Currently supports function type tools.

Show child attributes

tool_choice

padrão:auto

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

logprobs

boolean

padrão:false

Whether to return log probabilities of the output tokens.

top_logprobs

integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

Intervalo necessário: 0 <= x <= 20

reasoning_effort

enum<string>

Controls the reasoning effort for o-series and GPT-5.1+ models.

Opções disponíveis:

low,

medium,

high

stream_options

object

Options for streaming. Only valid when stream is true.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

Opções disponíveis:

auto,

default,

flex,

priority

Resposta

Successful chat completion response.

string

Unique completion identifier.

Exemplo:

"chatcmpl-abc123"

object

enum<string>

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

Opções disponíveis:

chat.completion

Exemplo:

"chat.completion"

created

integer

Unix timestamp of creation.

Exemplo:

1774412483

model

string

The model used (may include version suffix).

Exemplo:

"gpt-5.4-2026-03-05"

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 the provider reports one.

Exemplo:

"default"

system_fingerprint

string | null

Provider backend configuration fingerprint, when the provider reports one.

Exemplo:

"fp_490a4ad033"

APIs de texto e chat

Criar uma resposta de modelo

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-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "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"
  }
}

Moderação de conteúdo

Chaves de API

Funções das mensagens

Enviar entrada multimodal

Transmitir respostas

Solicitar saída estruturada

Chamar ferramentas e funções

Observações entre provedores

Perguntas frequentes

Como lidar com limites de taxa?

Como manter o contexto da conversa?

O que `finish_reason` querdizer?

Como controlar os custos?

Autorizações

Corpo

Resposta

​Funções das mensagens

​Enviar entrada multimodal

​Transmitir respostas

​Solicitar saída estruturada

​Chamar ferramentas e funções

​Observações entre provedores

​Perguntas frequentes

​Como lidar com limites de taxa?

​Como manter o contexto da conversa?

​O que finish_reason querdizer?

​Como controlar os custos?

Autorizações

Corpo

Resposta

Funções das mensagens

Enviar entrada multimodal

Transmitir respostas

Solicitar saída estruturada

Chamar ferramentas e funções

Observações entre provedores

Perguntas frequentes

Como lidar com limites de taxa?

Como manter o contexto da conversa?

O que `finish_reason` querdizer?

Como controlar os custos?