Crear Chat con Reconocimiento de Imágenes (No Streaming)

Este endpoint se utiliza para enviar prompts que contienen texto e imágenes al modelo, y obtener un resultado de completado de chat generado en una sola respuesta. El modelo devolverá una descripción detallada o una respuesta basada en el contexto proporcionado y el contenido de la imagen.

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

Encabezados de la Solicitud (Headers)

Parámetro	Requerido	Tipo	Ejemplo	Descripción
Content-Type	Sí	String	`application/json`	Formato del cuerpo de la solicitud
Accept	Sí	String	`application/json`	Formato del cuerpo de la respuesta
Authorization	No	String	`Bearer {{YOUR_API_KEY}}`	Clave API utilizada para la autenticación

Cuerpo de la Solicitud (Request Body)

Parámetro	Requerido	Tipo	Valor por Defecto	Descripción
model	Sí	String	-	ID del modelo a utilizar (ej. `gpt-4o`).
messages	Sí	Array	-	Lista de mensajes del chat. Para el reconocimiento de imágenes, `content` debe ser un array de objetos.
temperature	No	Number	1	Temperatura de muestreo (0-2). Valores más altos (ej. 1.8) hacen que la salida sea más aleatoria, valores más bajos la hacen más determinista.
top_p	No	Number	1	Probabilidad de muestreo de núcleo (nucleus sampling). Se recomienda modificar este o `temperature`, pero no ambos.
max_tokens	No	Integer	inf	Número máximo de Tokens a generar en la respuesta.
n	No	Integer	1	Cuántas respuestas alternativas generar por cada entrada.
stream	No	Boolean	false	Indica si se utiliza la salida en streaming. En este endpoint se fija en `false`.
stop	No	String/Array	null	Secuencia de parada. Soporta hasta 4 secuencias donde la API dejará de generar más tokens.
presence_penalty	No	Number	0	Penalización de presencia (-2.0 a 2.0). Valores positivos aumentan la probabilidad de que el modelo hable de nuevos temas.
frequency_penalty	No	Number	0	Penalización de frecuencia (-2.0 a 2.0). Valores positivos reducen la probabilidad de que el modelo repita las mismas frases.
response_format	No	Object	-	Especifica el formato de salida, ej. `{ "type": "json_object" }` para activar el modo JSON.
user	No	String	-	Identificador único del usuario final, ayuda a monitorear y detectar abusos.
tools	No	Array	-	Lista de herramientas que el modelo puede llamar (actualmente solo soporta `function`).
tool_choice	No	Object	-	Controla el comportamiento del modelo al llamar herramientas (`none`/`auto`/función específica).

Estructura del Objeto de Visión en messages (Content Array)

Al realizar una solicitud de reconocimiento de imágenes, el campo messages.content debe contener la siguiente estructura:

type: "text" o "image_url"
text: Cuando el tipo sea text, introduce la pregunta en texto.
image_url: Cuando el tipo sea image_url, introduce el objeto { "url": "URL de la imagen" }.

Ejemplo de Solicitud (Request Example)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "¿Qué hay en esta imagen? Por favor, descríbelo en detalle."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ]
}

Parámetros de Respuesta (Response Body)

Parámetro	Tipo	Descripción
id	String	Identificador único de la solicitud.
object	String	Tipo de objeto, siempre devuelve `chat.completion`.
created	Integer	Marca de tiempo de creación en formato Unix (segundos).
choices	Array	Contiene las opciones de respuesta generadas por el modelo.
└ index	Integer	Índice de la opción en el array.
└ message	Object	Objeto del mensaje devuelto por el modelo (contiene `role` y `content`).
└ finish_reason	String	Razón por la cual el modelo dejó de generar (ej. `stop`, `length`).
usage	Object	Estadísticas de uso de Tokens de la solicitud.
└ prompt_tokens	Integer	Número de Tokens consumidos por el prompt (incluyendo la imagen).
└ completion_tokens	Integer	Número de Tokens consumidos por la respuesta generada.
└ total_tokens	Integer	Número total de Tokens consumidos.

Ejemplo de Respuesta (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Esta imagen muestra un escritorio de oficina ordenado con una computadora portátil, una taza de café y una planta suculenta."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 45,
        "total_tokens": 165
    }
}

Preguntas Frecuentes (FAQs)

P: ¿Qué modelos soportan la función de reconocimiento de imágenes? R: Actualmente, la API soporta modelos multimodales como gpt-4o, gpt-4-turbo y gpt-4-vision-preview. Asegúrate de introducir el ID correcto en el parámetro model.

P: ¿Qué formatos de imagen se admiten? R: Se admiten los formatos de imagen más comunes, como PNG, JPEG, WEBP y GIF (no animados).

P: ¿Existen restricciones de permisos para las URLs de las imágenes? R: La URL de la imagen proporcionada debe ser de acceso público. Si la imagen está en un almacenamiento en la nube privado, debes generar una URL temporal prefirmada o convertir la imagen a codificación Base64 antes de enviarla (Nota: El formato Base64 debe seguir la estructura data:image/jpeg;base64,...).

P: ¿Cómo se factura el reconocimiento de imágenes? R: Las imágenes se convierten en Tokens para la facturación según su resolución y nivel de detalle. Por lo general, las imágenes de baja resolución consumen una cantidad pequeña y fija de Tokens, mientras que para las de alta resolución, los Tokens se calculan basándose en la cantidad de cuadrículas de 512x512 en las que se divide la imagen.

P: ¿Qué debo hacer si quiero una salida en streaming (efecto máquina de escribir)? R: Establece el parámetro stream en true en tu solicitud. Sin embargo, ten en cuenta que esta documentación describe específicamente las respuestas sin streaming. Si usas streaming, el formato de los datos devueltos cambiará a Server-Sent Events (SSE).

P: ¿Por qué la API devolvió "finish_reason": "length"? R: Esto indica que la respuesta generada alcanzó el límite establecido en el parámetro max_tokens o excedió el límite de la ventana de contexto del modelo, lo que provocó que el contenido se truncara.