Documentação da API de Conclusão de Chat (Chat Completions)

Esta API é usada para fornecer uma série de mensagens de conversa, e o modelo retornará um ou mais resultados de conclusão previstos. Suporta saída contínua (streaming), chamada de ferramentas (Function Calling) e vários ajustes de parâmetros de amostragem.

1. Informações do Endpoint

Nome do Endpoint: Teste N Oficial
Método da Requisição: POST
URL da Requisição: https://api.codingplanx.ai/v1/chat/completions
Content-Type: application/json
Autenticação: Bearer {{YOUR_API_KEY}}

2. Cabeçalhos da Requisição (Headers)

Parâmetro	Obrigatório	Tipo	Descrição	Exemplo
Content-Type	Sim	string	Identificador do tipo de mídia	`application/json`
Accept	Sim	string	Formato de resposta aceito pelo cliente	`application/json`
Authorization	Não	string	Token de acesso da API	`Bearer sk-xxxxxx`

3. Corpo da Requisição (Request Body)

Parâmetro	Obrigatório	Tipo	Descrição
model	Sim	string	O ID do modelo a ser usado (ex: `gpt-4o`, `gpt-3.5-turbo`).
messages	Sim	array	Lista de mensagens da conversa. Cada objeto contém `role` (system/user/assistant) e `content`.
tools	Sim	array	Lista de ferramentas que o modelo pode chamar. Atualmente suporta apenas funções.
tool_choice	Sim	object	Controla qual função o modelo deve chamar. `none` (nenhuma), `auto` (automático) ou especificar uma função específica.
temperature	Não	number	Temperatura de amostragem (0-2). Valores mais altos tornam a saída mais aleatória, enquanto valores mais baixos a tornam mais determinística. Recomenda-se alterar este ou `top_p`, mas não ambos.
top_p	Não	number	Amostragem de núcleo (nucleus sampling). 0.1 significa que apenas os tokens que compõem os 10% da massa de probabilidade superior são considerados.
n	Não	integer	Padrão é 1. Número de respostas geradas para cada mensagem de entrada.
stream	Não	boolean	Padrão é false. Se true, envia tokens de forma incremental (streaming), como o ChatGPT.
stop	Não	string	Sequência de parada. O modelo para de gerar tokens quando encontra esses caracteres.
max_tokens	Não	integer	O número máximo de tokens a serem gerados. Padrão é infinito (inf).
presence_penalty	Não	number	Entre -2.0 e 2.0. Penaliza tópicos que já apareceram, aumentando a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	Não	number	Entre -2.0 e 2.0. Penaliza palavras ou frases repetidas.
logit_bias	Não	object	Modifica a probabilidade de tokens específicos aparecerem.
user	Não	string	Identificador do usuário final, usado para detectar abusos.
response_format	Não	object	Especifica o formato de retorno. Por exemplo, `{ "type": "json_object" }` ativa o modo JSON.
seen	Não	integer	Função em fase de testes. Especifica a semente (Seed) para tentar obter saídas determinísticas.

4. Parâmetros de Resposta (Response Body)

Parâmetro	Tipo	Descrição
id	string	Identificador único para esta requisição.
object	string	Tipo de objeto, geralmente `chat.completion`.
created	integer	Timestamp de quando a requisição foi criada (em segundos).
choices	array	Lista de opções de respostas.
├─ index	integer	Índice desta opção na lista.
├─ message	object	Mensagem específica gerada pelo modelo.
│ ├─ role	string	O papel, geralmente `assistant`.
│ └─ content	string	O conteúdo de texto da mensagem.
└─ finish_reason	string	O motivo pelo qual a geração parou (ex: `stop`, `length`, `tool_calls`).
usage	object	Estatísticas de uso de tokens.
├─ prompt_tokens	integer	Número de tokens consumidos pela entrada (prompt).
├─ completion_tokens	integer	Número de tokens consumidos pela saída (geração).
└─ total_tokens	integer	Número total de tokens consumidos.

5. Exemplos (Examples)

Exemplo de Requisição

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "who are u?"
        }
    ],
    "n": 1,
    "max_tokens": 100,
    "temperature": 0.8,
    "stream": false
}

Exemplo de Resposta

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

6. Perguntas Frequentes (FAQs)

Q: Por que recebo um erro quando defino response_format: { "type": "json_object" }? A: Ao usar o modo JSON, você deve instruir explicitamente o modelo a gerar JSON através de uma mensagem do sistema ou do usuário no array messages (exemplo: "Por favor, responda em formato JSON"). Caso contrário, o modelo pode travar ou retornar um erro por não conseguir gerar um formato JSON válido.

Q: Posso ajustar temperature e top_p ao mesmo tempo? A: Tecnicamente sim, mas a recomendação oficial é escolher apenas um. Ajustar um deles geralmente é suficiente para alterar a aleatoriedade da saída. Ajustar ambos simultaneamente pode tornar os resultados imprevisíveis.

Q: Como recebo os dados quando stream: true está ativado? A: Quando a transmissão contínua (streaming) está ativada, o servidor envia uma série de Server-Sent Events (SSE). A parte de dados de cada evento é um objeto JSON e terminará com data: [DONE]. Você precisará usar uma biblioteca de análise de fluxo (como response.iter_lines() no Python) para processá-lo linha por linha.

Q: Como calculo o consumo de Tokens? A: Para o inglês, 1 token equivale a aproximadamente 4 caracteres ou 0,75 de uma palavra; para o chinês, 1 caractere pode corresponder a 1-2 tokens. O consumo final oficial deve ser baseado no campo usage retornado no corpo da resposta.

Q: O que significa quando aparece finish_reason: "length"? A: Isso indica que o conteúdo gerado excedeu o limite que você definiu em max_tokens, ou atingiu o limite máximo de comprimento de contexto do modelo, fazendo com que o conteúdo fosse truncado.

Q: A API suporta chamada de função (Function Calling)? A: Sim. Ao definir os protótipos das funções através do parâmetro tools, o modelo retornará tool_calls dentro de choices[0].message em vez do content normal, dependendo da necessidade da interação.