Documentação da API de Chat Completions

Esta interface é usada para fornecer um prompt (Prompt), e o modelo retornará um ou mais resultados de conclusão (completions) previstos. Você pode gerar texto com base no histórico da conversa e controlar a aleatoriedade, o comprimento e o formato do processo de geração.

Nome da Interface: Listar Modelos / Chat Completions
Método de Requisição: GET (Nota: conforme a definição dos dados fornecidos)
Endpoint da Requisição: https://api.codingplanx.ai/v1/models
Status: Publicado (Released)

1. Parâmetros da Requisição

1.1 Parâmetros de Header (Cabeçalho)

Nome do Parâmetro	Obrigatório	Tipo	Valor de Exemplo	Descrição
Content-Type	Sim	String	`application/json`	Formato do corpo da requisição da interface
Accept	Sim	String	`application/json`	Formato da resposta da interface
Authorization	Não	String	`Bearer {{YOUR_API_KEY}}`	Chave de API usada para autenticação

1.2 Parâmetros de Body (Corpo)

Embora a definição original seja GET, com base na lógica de negócios, os seguintes parâmetros geralmente são passados por meio de um JSON Body.

Nome do Parâmetro	Tipo	Obrigatório	Padrão	Descrição
model	string	Sim	-	ID do modelo a ser usado. Exemplo: `gpt-3.5-turbo`.
messages	array	Sim	-	Lista de mensagens incluídas na conversa até o momento. Cada mensagem contém um `role` (papel) e `content` (conteúdo).
temperature	number	Não	1	Temperatura de amostragem, entre 0 e 2. Valores mais altos tornam a saída mais aleatória.
top_p	number	Não	1	Amostragem de núcleo (nucleus sampling). 0.1 significa que apenas os tokens que compõem os top 10% da massa de probabilidade são considerados.
n	integer	Não	1	Quantas opções de conclusão de chat gerar para cada entrada.
stream	boolean	Não	false	Se deve usar streaming. Quando definido como true, enviará deltas parciais de mensagens via Server-Sent Events (SSE).
stop	string/array	Não	null	Sequência de parada. O modelo parará de gerar quando encontrar esses caracteres.
max_tokens	integer	Não	inf	Número máximo de tokens a serem gerados na saída.
presence_penalty	number	Não	0	Número 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	Número entre -2.0 e 2.0. Valores positivos diminuem a probabilidade de o modelo repetir as mesmas frases.
logit_bias	object	Não	null	Modifica a probabilidade de tokens específicos aparecerem na conclusão.
user	string	Não	-	Identificador único representando o usuário final, ajudando a monitorar abusos.
response_format	object	Não	-	Especifica o formato de saída do modelo, como `{ "type": "json_object" }` para ativar o modo JSON.
tools	array	Não	-	Lista de ferramentas (como funções) que o modelo pode chamar.
tool_choice	object	Não	auto	Controla qual função o modelo chamará.

2. Parâmetros de Resposta

Nome do Parâmetro	Tipo	Descrição
id	string	Identificador único para esta requisição.
object	string	Tipo de objeto, geralmente `chat.completion`.
created	integer	Timestamp (em segundos) de quando a requisição foi criada.
choices	array	Lista contendo os resultados da conclusão.
├─ index	integer	Índice desta escolha na lista.
├─ message	object	A mensagem específica gerada pelo modelo.
│ ├─ role	string	Papel, geralmente `assistant` (assistente).
│ └─ content	string	Conteúdo do texto da mensagem.
└─ finish_reason	string	Motivo da parada, como `stop` (parada normal) ou `length` (atingiu o limite máximo de tokens).
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 gerados na saída (completion).
└─ total_tokens	integer	Número total de tokens consumidos.

3. Exemplos de Requisição

Exemplo de Requisição Bem-sucedida

curl --location --request GET 'https://api.codingplanx.ai/v1/models' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "Hello there, how may I assist you today?"
    }
  ],
  "temperature": 1,
  "top_p": 1,
  "n": 1,
  "stream": false,
  "user": "user-1234"
}'

Exemplo de Resposta Bem-sucedida

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

4. FAQs (Perguntas Frequentes)

Q: Por que a documentação mostra o método GET, mas parece uma requisição POST? A: Na especificação padrão da OpenAI, a criação de completions geralmente usa o método POST. No entanto, de acordo com os metadados que você forneceu, esta interface está definida como GET. Certifique-se de confirmar a configuração real do lado do servidor ao fazer a chamada. Se o GET não funcionar, tente usar o POST.

Q: Como devo escolher entre temperature e top_p? A: Recomendamos ajustar apenas um deles. Se você deseja respostas mais precisas e determinísticas, diminua a temperature (ex: 0.2); se deseja respostas mais diversificadas e criativas, pode aumentá-la.

Q: Como ativar o modo JSON? A: Você precisa definir { "type": "json_object" } no parâmetro response_format e instruir explicitamente o modelo (nas mensagens de System ou User) que a saída deve ser no formato JSON. Caso contrário, o modelo pode gerar erros de análise ou um fluxo infinito de espaços em branco.

Q: O que são presence_penalty e frequency_penalty? A:

presence_penalty (Penalidade de Presença): Foca em penalizar tópicos que já apareceram, incentivando o modelo a falar sobre novos assuntos.
frequency_penalty (Penalidade de Frequência): Foca em penalizar palavras/termos que se repetem, evitando que o modelo repita as mesmas frases em um curto período de tempo.

Q: Como funciona a saída em fluxo (stream: true)? A: Ao ativar o streaming, a API retornará os dados palavra por palavra via Server-Sent Events (SSE). Cada bloco de dados é uma string JSON começando com data: e terminando com data: [DONE]. Isso é extremamente útil para a exibição em tempo real da geração de textos longos no frontend.