Criar Chat Completions (Não-Streaming)

Este endpoint é usado para, dado um prompt (instrução), retornar um ou mais resultados de preenchimento (completions) previstos pelo modelo. A interface não-streaming retorna o resultado de uma só vez após a geração da resposta completa.

Endpoint: https://api.codingplanx.ai/v1/chat/completions
Método da Requisição: POST
Content-Type: application/json

Parâmetros da Requisição

Cabeçalhos (Headers)

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
Content-Type	string	Sim	`application/json`	Formato do corpo da requisição
Accept	string	Sim	`application/json`	Formato do corpo da resposta
Authorization	string	Não	`Bearer {{YOUR_API_KEY}}`	Token de autenticação

Corpo da Requisição (Body)

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
model	string	Sim	-	ID do modelo a ser usado (ex: `gpt-4o`, `gpt-3.5-turbo`).
messages	array	Sim	-	Lista de mensagens da conversa. Cada objeto contém `role` (system/user/assistant) e `content`.
temperature	number	Não	1	Temperatura de amostragem (0-2). Valores maiores tornam a saída mais aleatória, valores menores mais determinísticos.
top_p	number	Não	1	Amostragem de núcleo (nucleus sampling). Considera apenas os tokens com massa de probabilidade top_p. Recomenda-se alterar este ou a `temperature`, não ambos.
n	integer	Não	1	Número de escolhas de completion a serem geradas para cada mensagem de entrada.
stream	boolean	Não	false	Se utiliza transmissão contínua (streaming). Aqui deve ser definido como `false`.
stop	string/array	Não	null	Sequência limite (até 4) onde a API parará de gerar novos tokens.
max_tokens	integer	Não	inf	Número máximo de tokens a serem gerados, limitado pelo tamanho do contexto do modelo.
presence_penalty	number	Não	0	Entre -2.0 e 2.0. Valores positivos aumentam a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	number	Não	0	Entre -2.0 e 2.0. Valores positivos reduzem a probabilidade de o modelo repetir as mesmas palavras.
logit_bias	object	Não	null	Modifica a probabilidade de tokens específicos aparecerem na resposta gerada.
user	string	Não	-	Identificador único do usuário final, usado para detectar abusos do sistema.
response_format	object	Não	-	Especifica o formato de saída, como `{ "type": "json_object" }` para ativar o modo JSON.
tools	array	Não	-	Lista de ferramentas que o modelo pode chamar (atualmente suporta apenas function).
tool_choice	string/obj	Não	auto	Controla qual função o modelo irá chamar (none/auto/função específica).

Parâmetros de Resposta

Corpo da Resposta (Response Body)

Parâmetro	Tipo	Descrição
id	string	Identificador único desta requisição.
object	string	Tipo do objeto, fixo como `chat.completion`.
created	integer	Timestamp Unix (em segundos).
choices	array	Lista com os resultados gerados (completions).
├─ index	integer	Índice deste resultado na lista.
├─ message	object	Conteúdo da mensagem gerada pelo modelo.
│ ├─ role	string	Papel (role), geralmente `assistant`.
│ └─ content	string	Conteúdo de texto específico da mensagem.
└─ finish_reason	string	Motivo da parada (ex: `stop`, `length`, `tool_calls`).
usage	object	Estatísticas de uso de tokens.
├─ prompt_tokens	integer	Número de tokens consumidos pelo prompt de entrada.
├─ completion_tokens	integer	Número de tokens gerados na resposta.
└─ total_tokens	integer	Número total de tokens consumidos.

Exemplos

Exemplo de Requisição (cURL)

curl --location --request POST 'https://api.codingplanx.ai/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Olá, por favor, apresente-se."
    }
  ],
  "max_tokens": 1000
}'

Exemplo de Resposta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Olá! Sou um assistente de IA fornecido pela CodingPlanX. Como posso ajudar você hoje?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 25,
        "total_tokens": 40
    }
}

FAQs (Perguntas Frequentes)

Q1: Como ativar o modo JSON? A1: No corpo da requisição, configure "response_format": { "type": "json_object" }. Nota: Ao usar o modo JSON, você deve instruir explicitamente o modelo a produzir JSON na mensagem system ou user, caso contrário, o modelo pode gerar um loop infinito de conteúdo em branco.

Q2: Como devo escolher entre temperature e top_p? A2: Geralmente recomendamos alterar apenas um deles. Se você precisa que o modelo seja mais criativo, aumente a temperature (ex: 0.8); se precisa de respostas mais rigorosas, precisas e determinísticas, diminua-a (ex: 0.2).

Q3: Por que o finish_reason é length? A3: Isso indica que a resposta gerada foi truncada porque atingiu o limite de max_tokens que você definiu ou excedeu o limite máximo de contexto permitido pelo modelo.

Q4: O que é um Token? A4: O Token é a unidade básica de processamento de texto do modelo. Para o idioma chinês, um caractere equivale a cerca de 1 a 2 tokens (em idiomas ocidentais, um token geralmente corresponde a uma sílaba ou pedaço de palavra). A cobrança e os limites de contexto da API são baseados na quantidade total de tokens.

Q5: Qual é a diferença entre presence_penalty e frequency_penalty? A5: A presence_penalty (penalidade de presença) foca em "falar sobre novos tópicos", ou seja, aplica uma penalidade se a palavra já apareceu no texto; a frequency_penalty (penalidade de frequência) foca na "quantidade de repetições", ou seja, quanto mais vezes a palavra aparece, maior será a penalidade aplicada.

Q6: O que devo fazer se quiser o efeito de geração de texto em tempo real (como digitando)? A6: Por favor, defina o parâmetro stream como true. Note que o formato da resposta por streaming é diferente deste documento (que é não-streaming) e é baseado na tecnologia Server-Sent Events (SSE).