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

Este endpoint é utilizado para enviar prompts contendo texto e imagens para o modelo, obtendo uma única resposta de conclusão de chat (chat completion). O modelo retornará descrições detalhadas ou respostas com base no contexto inserido e no conteúdo da imagem.

URL do Endpoint: https://api.codingplanx.ai/v1/chat/completions
Método HTTP: POST
Status: Publicado (Released)

Cabeçalhos da Requisição (Headers)

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 do corpo da resposta
Authorization	Não	String	`Bearer {{YOUR_API_KEY}}`	Chave de API utilizada para autenticação

Corpo da Requisição (Request Body)

Parâmetro	Obrigatório	Tipo	Padrão	Descrição
model	Sim	String	-	ID do modelo a ser utilizado (ex: `gpt-4o`).
messages	Sim	Array	-	Lista de mensagens do chat. Para análise de imagens, o `content` deve receber um array de objetos.
temperature	Não	Number	1	Temperatura de amostragem (0 a 2). Valores mais altos tornam o resultado mais aleatório; mais baixos, mais determinísticos.
top_p	Não	Number	1	Probabilidade de amostragem de núcleo (nucleus sampling). Recomenda-se alterar este parâmetro ou `temperature`, mas não ambos.
max_tokens	Não	Integer	inf	Número máximo de Tokens a serem gerados.
n	Não	Integer	1	Quantidade de respostas alternativas geradas para cada entrada de prompt.
stream	Não	Boolean	false	Se deve usar saída em streaming. Fixo como `false` para este endpoint.
stop	Não	String/Array	null	Sequência(s) de parada. Suporta até 4 sequências onde a API interromperá a geração.
presence_penalty	Não	Number	0	Penalidade de presença (-2.0 a 2.0). Aumenta a probabilidade do modelo falar sobre novos tópicos.
frequency_penalty	Não	Number	0	Penalidade de frequência (-2.0 a 2.0). Diminui a probabilidade do modelo repetir as mesmas frases ou termos.
response_format	Não	Object	-	Especifica o formato de saída, ex: `{ "type": "json_object" }` para ativar o modo JSON.
user	Não	String	-	Identificador único do usuário final.
tools	Não	Array	-	Lista de ferramentas que o modelo pode chamar (atualmente suporta apenas functions).
tool_choice	Não	Object	-	Controla o comportamento do modelo ao chamar ferramentas (none/auto/função específica).

Estrutura do Objeto de Imagem em messages (Content Array)

Ao realizar uma requisição com reconhecimento de imagem, o messages.content deve conter a seguinte estrutura:

type: "text" ou "image_url"
text: Quando o type for "text", insira a pergunta ou prompt em texto.
image_url: Quando o type for "image_url", insira o objeto { "url": "URL_da_imagem" }.

Exemplo de Requisição (Request)

{
    "model": "gpt-4o",
    "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": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ]
}

Parâmetros de Resposta (Response Body)

Parâmetro	Tipo	Descrição
id	String	Identificador único desta requisição.
object	String	Tipo de objeto, fixo como `chat.completion`.
created	Integer	Timestamp Unix (em segundos).
choices	Array	Lista contendo as múltiplas opções geradas.
└ index	Integer	Índice da opção.
└ message	Object	Objeto de mensagem retornado pelo modelo (contém `role` e `content`).
└ finish_reason	String	Motivo pelo qual o modelo parou de gerar (ex: `stop`, `length`).
usage	Object	Estatísticas de uso de Tokens.
└ prompt_tokens	Integer	Tokens consumidos pelo prompt (entrada).
└ completion_tokens	Integer	Tokens consumidos pelo resultado gerado.
└ total_tokens	Integer	Total de Tokens consumidos na requisição.

Exemplo de Resposta (Response)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Esta imagem mostra uma mesa de escritório arrumada com um laptop, uma xícara de café e uma planta suculenta."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 45,
        "total_tokens": 165
    }
}

Perguntas Frequentes (FAQs)

P: Quais modelos suportam a funcionalidade de reconhecimento de imagem? R: Atualmente, o suporte principal é para modelos multimodais como gpt-4o, gpt-4-turbo e gpt-4-vision-preview. Certifique-se de passar o ID correto no campo model.

P: Quais formatos de imagem são suportados? R: Suportamos os formatos de imagem mais comuns da web, como PNG, JPEG, WEBP e arquivos GIF não animados.

P: Existem restrições de permissão para os links das imagens? R: A URL da imagem fornecida deve ser publicamente acessível. Se a imagem estiver hospedada em um armazenamento em nuvem privado, gere um link de acesso temporário assinado ou converta a imagem para codificação Base64 antes de enviá-la (Nota: O Base64 deve seguir o formato URI de dados data:image/jpeg;base64,...).

P: Como funciona o faturamento (cobrança) do reconhecimento de imagens? R: As imagens são convertidas em Tokens para faturamento com base em sua resolução e nível de detalhes. Geralmente, imagens de baixa resolução consomem uma quantidade pequena e fixa de Tokens, enquanto imagens de alta resolução têm seu custo em Tokens calculado com base no número de recortes (tiles) de 512x512 pixels.

P: O que devo fazer se quiser uma saída em streaming (efeito de máquina de escrever)? R: Por favor, defina o parâmetro stream como true no corpo da requisição. No entanto, observe que as instruções desta documentação são focadas em retornos não-streaming. O formato de dados para respostas em streaming mudará para Server-Sent Events (SSE).

P: Por que a API retornou "finish_reason": "length"? R: Isso indica que a resposta gerada atingiu o limite que você definiu no parâmetro max_tokens ou excedeu a capacidade (janela de contexto) do modelo, fazendo com que o conteúdo fosse truncado/cortado.