Criar Endpoint de Chat com Reconhecimento de Imagem (Streaming / Não Streaming)

Esta API suporta entrada multimodal, permitindo aos usuários enviar texto e URLs de imagens durante a conversa. O modelo gerará respostas apropriadas com base no prompt inserido e no conteúdo da imagem. Suporta saída em fluxo (Streaming) para proporcionar uma experiência de interação mais fluida.

URL do Endpoint: https://api.codingplanx.ai/v1/chat/completions
Método da Requisição: POST
Referência Oficial: OpenAI Chat Completion API

Parâmetros da Requisição

Parâmetros de Header (Cabeçalho)

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

Parâmetros de Body (Corpo)

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
model	string	Sim	-	ID do modelo a ser utilizado (ex: `gpt-4o`, `gpt-4-vision-preview`).
messages	array	Sim	-	Lista de mensagens da conversa até o momento. Veja a estrutura de `messages` abaixo.
stream	boolean	Não	`false`	Se ativa a saída em streaming. Quando ativado, envia eventos Server-Sent Events (SSE).
temperature	number	Não	`1`	Temperatura de amostragem (0-2). Valores maiores tornam a saída mais aleatória; menores, mais determinística.
top_p	number	Não	`1`	Probabilidade de amostragem de núcleo (nucleus sampling). Recomenda-se alterar este ou `temperature`, mas não ambos.
max_tokens	integer	Não	inf	Número máximo de tokens a serem gerados no chat completion.
n	integer	Não	`1`	Quantas respostas de completion gerar para cada mensagem de entrada.
presence_penalty	number	Não	`0`	(-2.0 a 2.0) Valores positivos aumentam a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	number	Não	`0`	(-2.0 a 2.0) Valores positivos diminuem a probabilidade de o modelo repetir as mesmas palavras.
response_format	object	Não	-	Especifica o formato de saída, ex: `{"type": "json_object"}`.
stop	string/array	Não	null	Sequência (até 4) onde a API parará de gerar tokens.
user	string	Não	-	Identificador único do usuário final, útil para monitoramento e detecção de abusos.

Estrutura do objeto messages

Cada item na lista de mensagens contém os seguintes campos:

role: (string) Papel, as opções válidas são system, user, assistant, tool.
content: (string ou array) Conteúdo da mensagem.
- No modo de reconhecimento de imagem (visão), content é um array que contém objetos do tipo text e image_url.

Exemplo de Requisição

Requisição mista de Texto e Imagem (JSON)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Você é um assistente profissional de análise de imagens."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "O que há nesta imagem? Por favor, descreva detalhadamente."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

Descrição da Resposta

Resposta Não Streaming (stream: false)

Parâmetro	Tipo	Descrição
id	string	Identificador único da requisição.
object	string	Tipo de objeto, geralmente `chat.completion`.
created	integer	Timestamp de criação (em segundos).
choices	array	Lista de opções geradas pelo modelo.
choices[n].message	object	Objeto da mensagem retornada pelo modelo (contém `role` e `content`).
choices[n].finish_reason	string	Motivo da interrupção (ex: `stop`, `length`).
usage	object	Estatísticas de uso de tokens.

Exemplo de Resposta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Esta imagem mostra um lago tranquilo com uma cordilheira ao fundo."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

Resposta Streaming (stream: true)

Quando stream for true, o endpoint retorna text/event-stream. Cada linha começa com data: , seguida por uma string JSON. A última mensagem será data: [DONE].

FAQs (Perguntas Frequentes)

Q1: Como fazer o upload de imagens em vez de usar uma URL? R: Este endpoint suporta principalmente URLs de imagens. Se você possui apenas uma imagem local, recomendamos enviá-la para o seu provedor de hospedagem de imagens ou armazenamento de objetos (OSS) primeiro. Alternativamente, você pode converter a imagem para uma string codificada em Base64 no formato data:image/jpeg;base64,{base64_encode_data} e inseri-la no campo url.

Q2: Por que minha requisição em streaming não retornou as estatísticas de usage? R: No protocolo de streaming padrão compatível com OpenAI, o usage (uso) geralmente é retornado apenas no último bloco de dados ou através da configuração de um parâmetro especial stream_options. Verifique se a versão do seu modelo suporta o retorno de contagem de tokens no fluxo de dados.

Q3: Quais são as restrições de tamanho e formato para o reconhecimento de imagens? R: Geralmente são suportados os formatos PNG, JPEG, WEBP e GIF (não animados). Recomenda-se que o tamanho da imagem não exceda 20 MB. Para obter os melhores resultados de reconhecimento, sugere-se uma resolução de 512x512 ou superior.

Q4: O que devo fazer se minha requisição retornar o erro "401 Unauthorized"? R: Certifique-se de ter passado corretamente o campo Authorization no Header (Cabeçalho), no formato Bearer seguido da sua API KEY, e verifique se a chave é válida e possui saldo suficiente.

Q5: O parâmetro temperature afeta o reconhecimento de imagens? R: Sim. A temperature afeta a criatividade linguística do modelo ao descrever a imagem. Se você precisa de uma descrição muito objetiva e rigorosa, recomenda-se definir um valor mais baixo (ex: 0.2); se deseja uma descrição mais vívida e interessante, pode definir um valor mais alto (ex: 0.8).

Q6: Como processar o reconhecimento de múltiplas imagens? R: Você pode inserir vários objetos do tipo image_url no array messages.content. O modelo tentará compreender o conteúdo de todas essas imagens simultaneamente.