Criar Chat com Reconhecimento de Imagem (Streaming) Base64

Descrição do Endpoint: Dado um prompt, este modelo retornará uma ou mais opções de conclusão e também pode retornar as probabilidades de tokens alternativos em cada posição. Este endpoint é usado principalmente para criar conclusões de chat que contêm reconhecimento de imagem (baseado em Base64) e prompts de texto.

Referência Oficial: Documentação da API OpenAI

Detalhes do Endpoint

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 (Request 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 aceito
Authorization	Não	string	`Bearer {{SUA_API_KEY}}`	Token de autenticação

Corpo da Requisição (Request Body)

Nome do Campo	Tipo	Obrigatório	Descrição
model	string	Sim	O ID do modelo a ser utilizado (ex: `gpt-4o-mini`).
messages	array	Sim	Lista de mensagens que compõem a conversa até o momento. Contém `role` e `content`. Para reconhecimento de imagem, `content` pode ser um array contendo texto e `image_url` (Base64).
tools	array	Sim	Uma lista de ferramentas que o modelo pode chamar. Atualmente, suporta apenas funções como ferramentas. Usado para fornecer uma lista de funções para as quais o modelo pode gerar entradas JSON.
tool_choice	object	Sim	Controla qual função o modelo irá chamar. `none` significa não chamar nenhuma; `auto` significa seleção automática; também é possível forçar a chamada de uma função específica.
temperature	integer	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 simultaneamente com `top_p`.
top_p	integer	Não	Parâmetro de amostragem de núcleo (Nucleus sampling). 0.1 significa que apenas os tokens que compõem os top 10% da probabilidade de massa são considerados. Recomenda-se não modificar simultaneamente com `temperature`.
n	integer	Não	Quantas opções de conclusão de chat gerar para cada mensagem de entrada. O padrão é 1.
stream	boolean	Não	Interruptor de saída em streaming. O padrão é `false`. Se definido como `true`, enviará deltas parciais de mensagens como Eventos Enviados pelo Servidor (SSE) e será encerrado com a mensagem `data: [DONE]`.
stop	string	Não	Sequência onde a API parará de gerar novos tokens (máximo de 4 sequências). O padrão é null.
max_tokens	integer	Não	O número máximo de tokens a serem gerados na conclusão do chat. O padrão é inf (infinito).
presence_penalty	number	Não	Penalidade de presença (-2.0 a 2.0). Valores positivos penalizam novos tokens com base no fato de já terem aparecido no texto, aumentando a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	number	Não	Penalidade de frequência (-2.0 a 2.0). Valores positivos penalizam tokens com base em sua frequência atual no texto, diminuindo a probabilidade de o modelo repetir o mesmo conteúdo. O padrão é 0.
logit_bias	object	Não	Modifica a probabilidade de tokens especificados aparecerem na conclusão. Aceita um objeto JSON que mapeia IDs de tokens para valores de viés (-100 a 100).
user	string	Não	Identificador único que representa o usuário final, ajudando a monitorar e detectar abusos do sistema.
response_format	object	Não	Especifica o formato que o modelo deve gerar. Passar `{ "type": "json_object" }` ativa o modo JSON. Ao usar isso, é necessário instruir o modelo a gerar JSON no prompt.
seed (seen)	integer	Não	Funcionalidade Beta. Semente de amostragem determinística. Repetir requisições com a mesma semente (seed) e parâmetros deve retornar os mesmos resultados (o determinismo absoluto não é garantido).

Exemplo de Requisição

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "O que há nesta imagem? Por favor, descreva em detalhes."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiEAAAIhCAYAAACYF2qHAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR4nOy9ebxtWVXf+x1zrrX2Pud2VRQUjUVf0glIYvOJLdJ8iCagIor... (string base64 omitida devido ao tamanho)"
          }
        }
      ]
    }
  ]
}

Parâmetros da Resposta (Response Body)

Nome do Campo	Tipo	Descrição
id	string	Identificador único da conclusão do chat.
object	string	Tipo de objeto, geralmente `chat.completion` (ou `chat.completion.chunk` em casos de streaming).
created	integer	Timestamp Unix do momento da criação.
choices	array	Lista de opções de conclusão.
└─ index	integer	Índice da opção na lista.
└─ message	object	Objeto da mensagem gerada pelo modelo, contendo `role` e `content`.
└─ finish_reason	string	Motivo pelo qual o modelo parou de gerar (exemplo: `stop` representa um término normal, `length` representa que o limite de `max_tokens` foi atingido).
usage	object	Estatísticas de consumo de tokens desta requisição.
└─ prompt_tokens	integer	Quantidade de Tokens consumidos pelo prompt (incluindo os tokens calculados a partir da imagem).
└─ completion_tokens	integer	Quantidade de Tokens consumidos pelo conteúdo gerado.
└─ total_tokens	integer	Quantidade total de Tokens consumidos nesta requisição.

Exemplo de Resposta (Sucesso 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 ativar a saída em Streaming? A: Defina o parâmetro stream como true no corpo da requisição. Quando ativado, o endpoint não esperará a resposta inteira ser gerada para retornar; em vez disso, ele retornará fragmentos de dados no formato data: {...} em tempo real, via Eventos Enviados pelo Servidor (Server-Sent Events - SSE), até receber o marcador data: [DONE], que indica o fim da geração.

Q2: Quais são os requisitos para a codificação Base64 de imagens? A: A string Base64 da imagem deve conter o prefixo do tipo MIME correto, por exemplo, data:image/png;base64, ou data:image/jpeg;base64,. Recomenda-se comprimir adequadamente as dimensões da imagem antes de convertê-la para Base64 para reduzir a latência de transmissão de rede e diminuir o consumo de prompt_tokens (imagens muito grandes consumirão uma quantidade enorme de Tokens, podendo exceder o limite de contexto).

Q3: Por que a resposta do modelo foi cortada (truncada)? A: Por favor, verifique o valor de choices[0].finish_reason no corpo da resposta. Se for length, significa que o texto gerado atingiu o limite de max_tokens que você definiu, ou a conversa inteira ultrapassou a janela máxima de contexto do modelo. Você pode resolver este problema aumentando o valor de max_tokens.

Q4: Como forçar o modelo a retornar dados no formato JSON? A: Primeiro, é necessário definir "response_format": { "type": "json_object" } no corpo da requisição. Aviso Importante: Além de configurar este parâmetro, você deve exigir explicitamente que o modelo gere JSON usando linguagem natural no prompt do sistema (system prompt) ou no prompt do usuário dentro de messages (por exemplo: "Por favor, retorne o resultado no formato JSON"). Se isso não for feito, o modelo pode entrar em um ciclo infinito gerando espaços em branco até esgotar seus Tokens.

Q5: O que fazer se eu encontrar o erro 401 Unauthorized? A: Por favor, verifique se o parâmetro Authorization no cabeçalho da requisição contém corretamente a sua API Key. O formato deve ser estritamente Bearer SUA_API_KEY (certifique-se de que há um espaço entre a palavra "Bearer" e a "Key").