Controlar o Nível de Esforço de Raciocínio (Chat Completions)

Descrição do Endpoint

Dado um prompt, o modelo retornará uma ou mais previsões de resposta (suporta o controle do nível de esforço de raciocínio do modelo).

Referência da Documentação Oficial: Guias de Raciocínio da OpenAI
Status do Endpoint: Publicado (released)

Instruções da Requisição

Método da Requisição: POST
URL da Requisição: https://api.codingplanx.ai/v1/chat/completions

Cabeçalhos da Requisição (Headers)

Nome do Parâmetro	Obrigatório	Tipo	Valor de Exemplo	Descrição
`Content-Type`	Sim	`string`	`application/json`	Formato dos dados
`Accept`	Sim	`string`	`application/json`	Formato de aceitação
`Authorization`	Não	`string`	`Bearer {{YOUR_API_KEY}}`	Credenciais de autenticação

Parâmetros do Corpo (Body)

Formato dos dados: application/json

Nome do Parâmetro	Obrigatório	Tipo	Descrição
`model`	Sim	`string`	O ID do modelo a ser usado (por exemplo, `o4-mini`, etc.).
`messages`	Sim	`array`	Lista de mensagens que compõem a conversa até o momento. Contém `role` (ex: user/assistant) e `content` (conteúdo da mensagem).
`tools`	Sim	`array`	Lista de ferramentas (funções) que o modelo pode chamar. Usado para fornecer funções para as quais o modelo pode gerar entradas em JSON.
`tool_choice`	Sim	`object`	Controla qual função o modelo chamará. `none` significa não chamar nenhuma, `auto` significa seleção automática.
`reasoning_effort`	Não	`string`	Parâmetro Principal: Controla o nível de esforço (profundidade de pensamento) do modelo de raciocínio ao gerar a resposta. Valores opcionais comuns são `low` (baixo), `medium` (médio), `high` (alto).
`temperature`	Não	`number`	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. Recomenda-se modificar apenas este ou o `top_p`.
`top_p`	Não	`number`	Amostragem de núcleo (nucleus sampling). 0.1 significa que apenas os tokens que compõem os 10% do topo da massa de probabilidade serão considerados. Recomenda-se modificar apenas este ou a `temperature`.
`n`	Não	`integer`	O padrão é 1. Quantas opções de conclusão de chat gerar para cada mensagem de entrada.
`stream`	Não	`boolean`	O padrão é false. Se definido como true, enviará incrementos parciais da mensagem como Server-Sent Events (SSE) e encerrará o fluxo com `data: [DONE]`.
`stop`	Não	`string`	String de até 4 sequências onde a API parará de gerar novos tokens.
`max_tokens`	Não	`integer`	O número máximo de tokens a serem gerados na conclusão do chat. O comprimento total dos tokens de entrada e gerados é limitado pelo contexto do modelo.
`presence_penalty`	Não	`number`	Número entre -2.0 e 2.0. Valores positivos penalizam tokens novos com base no fato de já terem aparecido no texto, aumentando a probabilidade de o modelo falar sobre novos tópicos.
`frequency_penalty`	Não	`number`	Número entre -2.0 e 2.0. Valores positivos penalizam tokens novos com base em sua frequência atual no texto, reduzindo a probabilidade de repetir o mesmo conteúdo.
`logit_bias`	Não	`object`	Aceita um objeto JSON mapeando IDs de tokens para valores de viés (-100 a 100), usado para modificar a probabilidade de um token específico aparecer na conclusão.
`user`	Não	`string`	Identificador único que representa o usuário final, auxiliando no monitoramento e detecção de abusos.
`response_format`	Não	`object`	Especifica o formato que o modelo deve gerar. Por exemplo, `{"type": "json_object"}` ativa o modo JSON.
`seen`	Não	`integer`	Recurso em fase beta (semelhante ao seed). Se especificado, o sistema fará o possível para amostrar de forma determinística, permitindo que os mesmos parâmetros retornem os mesmos resultados.

Exemplo de Requisição

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Olá, por favor, explique em detalhes os princípios da computação quântica."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

Instruções de Resposta

Parâmetros do Corpo da Resposta

Formato dos dados: application/json

Nome do Parâmetro	Tipo	Descrição
`id`	`string`	O identificador único desta requisição.
`object`	`string`	Tipo do objeto, geralmente `chat.completion`.
`created`	`integer`	Timestamp do momento da criação.
`choices`	`array`	Lista com os resultados da conclusão.
└ `index`	`integer`	Índice da escolha atual na lista.
└ `message`	`object`	Corpo da mensagem gerada pelo modelo. Contém `role` e `content`.
└ `finish_reason`	`string`	Motivo pela qual a geração parou (ex: `stop`, `length`).
`usage`	`object`	Estatísticas de consumo de Tokens.
└ `prompt_tokens`	`integer`	Número de Tokens consumidos pelo prompt.
└ `completion_tokens`	`integer`	Número de Tokens consumidos pela geração do modelo.
└ `total_tokens`	`integer`	Número total de Tokens consumidos.

Exemplo de Resposta (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (Perguntas Frequentes)

1. Qual é a função do parâmetro `reasoning_effort`?

O parâmetro reasoning_effort é utilizado para controlar quanto recurso computacional e tempo os modelos com capacidades avançadas de raciocínio (Reasoning) (como a série o1/o4 da OpenAI) gastam em pensamentos internos antes de fornecer a resposta final. Normalmente suporta três níveis: low (baixo), medium (médio) e high (alto). Quando configurado para high, o modelo realiza deduções lógicas mais profundas, ideal para resolver problemas complexos de matemática ou programação; no entanto, o tempo de resposta também aumentará correspondentemente.

2. Por que, ao ativar `stream: true`, não recebo uma resposta JSON padrão?

Quando a transmissão contínua (stream: true) está ativada, a API utiliza o protocolo Server-Sent Events (SSE) para retornar blocos de dados (Chunks) continuamente. Cada bloco de dados é enviado no formato data: {...} e, quando todo o conteúdo terminar de ser transmitido, será enviada a mensagem data: [DONE]. Os desenvolvedores precisam ler o fluxo linha por linha e analisar a string JSON após data: para concatenar a resposta completa.

3. O documento menciona que se recomenda modificar apenas `temperature` ou `top_p`. Por quê?

Ambos os parâmetros são usados para controlar a aleatoriedade e a diversidade do conteúdo gerado pelo modelo. A temperature altera a distribuição de probabilidade escalando os logits, enquanto o top_p (Amostragem de núcleo) restringe o pool de candidatos ao cortar vocabulários com probabilidade acumulada mais baixa. Ajustar simultaneamente ambos os parâmetros fará com que o comportamento do modelo se torne difícil de prever e controlar. Portanto, a melhor prática é fixar um deles (geralmente mantendo o padrão) e ajustar apenas o outro para satisfazer as necessidades de controle da "aleatoriedade".

4. O que significa se o `finish_reason` retornar `"length"`?

Isso significa que a resposta do modelo foi forçadamente truncada (cortada). Geralmente, há dois motivos para isso: primeiro, a quantidade de Tokens gerados atingiu o limite definido no parâmetro max_tokens na requisição; segundo, o número total de Tokens (o seu Prompt da requisição mais a resposta gerada) excedeu o limite máximo da janela de contexto permitido por esse modelo. Neste caso, recomenda-se encurtar o histórico da conversa ou aumentar o valor do parâmetro max_tokens.

5. Como forçar o modelo a retornar os dados no formato JSON?

Você pode ativar o modo JSON passando "response_format": {"type": "json_object"} no corpo da requisição. MUITO IMPORTANTE: Ao ativar este modo, você deve solicitar explicitamente ao modelo em linguagem natural, dentro do campo messages (geralmente no prompt do system ou user), que a saída seja em JSON. Caso contrário, o modelo poderá entrar em um loop infinito gerando apenas espaços em branco até atingir o limite de Tokens.