Criar Geração de Imagens via Chat (Não-Streaming)

Este endpoint é utilizado para enviar um prompt (contendo texto ou imagem) ao modelo, que retornará uma ou mais respostas geradas. Ele é especialmente adequado para modelos que suportam entradas multimodais (como processamento de imagens, aprimoramento visual e criação baseada em reconhecimento de imagem), como o gpt-4o-image-vip.

Informações do Endpoint

URL do Endpoint: https://api.codingplanx.ai/v1/chat/completions
Método da Requisição: POST
Content-Type: application/json
Tipo de Resposta: application/json

Cabeçalhos da Requisição (Headers)

Nome do 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 de resposta esperado
Authorization	Não	String	`Bearer {{YOUR_API_KEY}}`	Chave de API (API Key) para autenticação

Parâmetros da Requisição (Body)

O corpo da requisição é um objeto JSON que contém os seguintes campos:

Nome do Parâmetro	Tipo	Obrigatório	Padrão	Descrição
model	String	Sim	-	ID do modelo a ser utilizado. Exemplo: `gpt-4o-image-vip`.
messages	Array	Sim	-	Lista de mensagens do chat. Cada objeto contém `role` (user/assistant/system) e `content`. O `content` pode ser uma string ou um array de objetos contendo o tipo e a URL da imagem.
tools	Array	Sim	-	Lista de ferramentas (tools) que o modelo pode chamar. Atualmente, suporta apenas funções.
tool_choice	Object	Sim	`none`	Controla qual função o modelo deve chamar. `none` para não chamar nenhuma, `auto` para escolha automática.
temperature	Number	Não	1	Temperatura de amostragem (0-2). Valores mais altos tornam a saída mais aleatória; valores mais baixos a tornam mais focada/determinística.
top_p	Number	Não	1	Amostragem de núcleo (Nucleus sampling). Considera apenas os tokens com probabilidade de massa top P. Recomenda-se alterar este ou temperature, mas não ambos.
n	Integer	Não	1	Número de opções de respostas (completions) a serem geradas para cada entrada.
stream	Boolean	Não	`false`	Se a resposta deve ser via streaming. Este endpoint atual é definido como não-streaming.
max_tokens	Integer	Não	inf	Número máximo de tokens a serem gerados.
stop	String/Array	Não	null	Sequência de parada (stop sequence). A API parará de gerar novos tokens quando encontrá-la.
presence_penalty	Number	Não	0	Entre -2.0 e 2.0. Penaliza novos tokens com base em sua presença no texto até agora, aumentando a probabilidade de o modelo falar sobre novos tópicos.
frequency_penalty	Number	Não	0	Entre -2.0 e 2.0. Penaliza novos tokens com base em sua frequência de uso no texto até o momento.
response_format	Object	Não	-	Especifica o formato de saída, como `{ "type": "json_object" }` para ativar o modo JSON.
user	String	Não	-	Identificador único que representa o usuário final, ajudando a monitorar e prevenir abusos.
seen	Integer	Não	-	(Beta) Especifica o valor da semente (seed) para tentar obter amostragens determinísticas.

Parâmetros de Resposta

Nome do Parâmetro	Tipo	Descrição
id	String	Identificador único para a requisição.
object	String	Tipo do objeto, sempre será `chat.completion`.
created	Integer	Carimbo de data/hora Unix (em segundos).
choices	Array	Contém as opções de respostas geradas.
└ index	Integer	O índice da opção no array.
└ message	Object	Objeto de mensagem contendo `role` e `content`.
└ finish_reason	String	Motivo da parada da geração (ex: `stop`, `length`).
usage	Object	Estatísticas de uso de tokens.
└ prompt_tokens	Integer	Número de tokens consumidos no prompt.
└ completion_tokens	Integer	Número de tokens consumidos na resposta (completion).
└ total_tokens	Integer	Total de tokens consumidos.

Exemplos

Exemplo de Requisição (Aprimoramento/Criação de Imagem)

{
    "model": "gpt-4o-image-vip",
    "messages": [
      {
            "role": "user",
            "content": [
                {"type": "text", "text": "Aprimore esta imagem, adicione as palavras 'Eu Amo a China' e ajuste a proporção para [4:3] "},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ],
    "tools": [],
    "tool_choice": "none"
}

Exemplo de Resposta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Certo, a imagem foi processada para você. Você pode conferir o resultado gerado aqui: [Link da Imagem/Descrição]"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (Perguntas Frequentes)

P: Por que a requisição retorna um erro ao usar response_format: { "type": "json_object" }? R: Ao usar o modo JSON, você deve instruir explicitamente o modelo a gerar JSON dentro de messages (por exemplo: adicionando "Por favor, responda no formato JSON" no prompt do sistema). Caso contrário, o modelo pode entrar em um loop infinito ou gerar um erro por produzir um conteúdo não-JSON.

P: Como garantir que os resultados gerados sejam consistentes em cada requisição? R: Embora os modelos de IA possuam aleatoriedade inerente, você pode tentar definir o parâmetro seen (seed) e manter a temperature em 0. Além disso, monitore o campo system_fingerprint na resposta para verificar se o ambiente de back-end sofreu alguma alteração.

P: Qual é o valor ideal para definir em max_tokens? R: Isso depende do seu cenário de uso. Para descrições curtas de imagens, um valor entre 100-300 é suficiente; se precisar de uma análise detalhada ou criação de texto longo, recomenda-se definir acima de 1000. Lembre-se de que a soma dos tokens de entrada (incluindo imagens) e de saída não pode exceder o limite de contexto do modelo.

P: Como lidar com a entrada de imagens? R: No campo content de messages, utilize type: "image_url". Atualmente, é fortemente recomendado o uso de links de imagens HTTPS que sejam publicamente acessíveis na internet.

P: Os parâmetros tools e tool_choice são obrigatórios? R: Com base na definição deste endpoint, esses dois campos estão marcados como obrigatórios. Se você não precisa que o modelo chame uma ferramenta específica, defina tools como um array vazio [] e tool_choice como "none".