Documentação da API: Criar Chamada de Função de Chat

Descrição da API

Dado um prompt, o modelo retornará um ou mais resultados de completamento previstos e pode retornar as probabilidades de tokens alternativos em cada posição. Esta API suporta especialmente a funcionalidade de Chamada de Função (Function Calling), permitindo que o modelo faça escolhas inteligentes entre gerar uma mensagem de texto e chamar uma função especificada.

Referência Oficial: Guia de Function Calling

Informações Básicas

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

Cabeçalhos da Requisição (Headers)

Nome do Parâmetro	Tipo	Obrigatório	Valor de Exemplo	Descrição
`Content-Type`	string	Sim	`application/json`	Tipo de conteúdo dos dados
`Accept`	string	Sim	`application/json`	Tipo de dados aceito pelo cliente
`Authorization`	string	Não	`Bearer {{YOUR_API_KEY}}`	Credencial de autenticação

Corpo da Requisição (Body)

Nome do Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	Sim	O ID do modelo a ser utilizado (exemplo: `gpt-4o`). Para detalhes sobre os modelos disponíveis, consulte a tabela de compatibilidade de endpoints de modelos.
`messages`	array	Sim	Uma lista de mensagens que compõem a conversa até o momento. Cada objeto deve conter os campos `role` e `content`.
`tools`	array	Sim	Uma lista de ferramentas que o modelo pode chamar. Atualmente, apenas funções são suportadas como ferramentas. Usado para fornecer uma lista de funções para as quais o modelo pode gerar entradas em JSON.
`tool_choice`	object/string	Sim	Controla qual função o modelo irá chamar (se houver). `none` significa não chamar nenhuma; `auto` significa que o modelo escolhe automaticamente. Também é possível forçar a chamada de uma função específica através de `{"type": "function", "function": {"name": "my_function"}}`.
`temperature`	number	Não	Temperatura de amostragem, entre 0 e 2. Valores mais altos (como 0.8) tornam a saída mais aleatória, enquanto valores mais baixos (como 0.2) a tornam mais determinística. Recomenda-se não modificar este parâmetro e o `top_p` ao mesmo tempo.
`top_p`	number	Não	Método de amostragem de núcleo (Nucleus sampling). 0.1 significa que apenas os tokens que compõem os top 10% da massa de probabilidade serão considerados. Recomenda-se não modificar este parâmetro e a `temperature` ao mesmo tempo.
`n`	integer	Não	Quantas escolhas de completamento de chat gerar para cada mensagem de entrada. O padrão é 1.
`stream`	boolean	Não	O padrão é false. Se definido como true, enviará deltas parciais de mensagens na forma de Server-Sent Events (SSE) e será encerrado com `data: [DONE]`.
`stop`	string/array	Não	Até 4 sequências onde a API parará de gerar tokens adicionais. O padrão é null.
`max_tokens`	integer	Não	O número máximo de tokens a serem gerados no completamento do chat. O comprimento total da entrada e da saída gerada é limitado pelo comprimento de contexto do modelo.
`presence_penalty`	number	Não	Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens baseando-se no fato de já terem aparecido ou não no texto, aumentando a probabilidade de o modelo falar sobre novos tópicos.
`frequency_penalty`	number	Não	Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens baseando-se em sua frequência atual no texto, reduzindo a probabilidade de o modelo repetir o mesmo conteúdo.
`logit_bias`	object	Não	Modifica a probabilidade de tokens específicos aparecerem no completamento. Aceita um objeto JSON que mapeia IDs de tokens para valores de viés (de -100 a 100).
`user`	string	Não	Um identificador único que representa seu usuário final, o que pode ajudar a monitorar e detectar abusos.
`response_format`	object	Não	Um objeto que especifica o formato no qual o modelo deve produzir a saída. Por exemplo, use `{ "type": "json_object" }` para ativar o modo JSON.
`seen`	integer	Não	Funcionalidade em fase de testes (Beta/Seed). Se especificado, o sistema tentará fazer a amostragem de forma determinística, de modo que requisições com a mesma semente (seed) e parâmetros retornem o mesmo resultado.

Exemplo do Corpo da Requisição

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful customer support assistant. Use the supplied tools to assist the user."
        },
        {
            "role": "user",
            "content": "Hi, can you tell me the delivery date for my order?"
        },
        {"role": "assistant", "content": "Hi there! I can help with that. Can you please provide your order ID?"},
        {"role": "user", "content": "i think it is order_12345"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_delivery_date",
                "description": "Get the delivery date for a customer's order. Call this whenever you need to know the delivery date, for example when a customer asks 'Where is my package'",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "order_id": {
                            "type": "string",
                            "description": "The customer's order ID."
                        }
                    },
                    "required": [
                        "order_id"
                    ],
                    "additionalProperties": false
                }
            }
        }
    ]
}

Parâmetros de Resposta (Response)

Nome do Parâmetro	Tipo	Descrição
`id`	string	O identificador único para o completamento do chat.
`object`	string	O tipo do objeto, geralmente `chat.completion`.
`created`	integer	Timestamp Unix de quando o completamento do chat foi criado.
`choices`	array	Lista de escolhas do completamento do chat.
? `index`	integer	O índice desta escolha na lista de opções.
? `message`	object	O objeto da mensagem de resposta gerada pelo modelo, contendo `role` e `content`.
? `finish_reason`	string	O motivo pelo qual o modelo parou de gerar tokens (como `stop`, `length` ou porque engatilhou uma chamada de função).
`usage`	object	Estatísticas de consumo de tokens para esta requisição.
? `prompt_tokens`	integer	Número de tokens consumidos pelo prompt (entrada).
? `completion_tokens`	integer	Número de tokens consumidos pela resposta gerada pelo modelo.
? `total_tokens`	integer	Número total de tokens consumidos nesta requisição.

Exemplo de Resposta (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
    }
}

Perguntas Frequentes (FAQs)

Q1: Como forçar o modelo a chamar uma função específica que eu determinei? R: Você pode conseguir isso definindo o parâmetro tool_choice. Por exemplo, se o nome da sua função for get_weather, você pode definir tool_choice como: {"type": "function", "function": {"name": "get_weather"}}. Dessa forma, o modelo ignorará respostas normais e será forçado a produzir os parâmetros para essa função.

Q2: Por que o conteúdo da minha resposta foi truncado (cortado)? R: Verifique o valor de choices[0].finish_reason na resposta. Se for "length", significa que o texto gerado excedeu o limite do parâmetro max_tokens que você definiu, ou que atingiu o comprimento máximo de contexto do modelo. Você pode tentar aumentar o valor de max_tokens.

Q3: Tanto temperature quanto top_p podem controlar a aleatoriedade, como devo usá-los? R: De fato, ambos os parâmetros ajustam a diversidade da saída do modelo. Valores mais altos tornam a saída mais criativa, enquanto valores mais baixos a tornam mais rigorosa e determinística. A recomendação oficial é ajustar apenas um deles e manter o outro com o valor padrão. Não modifique ambos simultaneamente para evitar resultados imprevisíveis.

Q4: Após ativar stream: true, qual é o formato dos dados retornados pela API? R: Ao ativar a transmissão de fluxo (streaming), a API não retorna mais um único objeto JSON, mas sim um fluxo de dados em Server-Sent Events (SSE). Os dados serão enviados em pedaços no formato data: {"id": "...", "choices": [{"delta": {"content": "..."}}]} . Quando a transmissão for concluída, a última mensagem será data: [DONE].

Q5: Quais são os cuidados ao ativar o response_format para o modo JSON? R: Ao definir response_format como { "type": "json_object" }, você deve instruir explicitamente o modelo dentro do array messages (no prompt do sistema ou do usuário) a gerar dados no formato JSON. Se você não fizer isso, o modelo poderá entrar em um loop infinito gerando espaços em branco, o que causará timeout na requisição ou atingirá o limite máximo de tokens.