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

Descripción del Endpoint: Dado un prompt (mensaje), el modelo devolverá una o más predicciones de completación, y también puede devolver las probabilidades de los tokens alternativos en cada posición. Este endpoint se utiliza principalmente para crear completaciones de chat que incluyen reconocimiento de imágenes (basado en Base64) y prompts de texto.

Referencia Oficial: Documentación de la API de OpenAI

Detalles del Endpoint

Método de solicitud: POST
URL de solicitud: https://api.codingplanx.ai/v1/chat/completions
Formato de datos: application/json

Encabezados de Solicitud (Request Headers)

Nombre del Parámetro	Obligatorio	Tipo	Valor de Ejemplo	Descripción
Content-Type	Sí	string	`application/json`	Formato de los datos
Accept	Sí	string	`application/json`	Formato aceptado
Authorization	No	string	`Bearer {{YOUR_API_KEY}}`	Token de autenticación

Cuerpo de la Solicitud (Request Body)

Nombre del Campo	Tipo	Obligatorio	Descripción
model	string	Sí	El ID del modelo a utilizar (ej. `gpt-4o-mini`).
messages	array	Sí	Una lista de mensajes que componen la conversación hasta el momento. Contiene `role` y `content`. Para el reconocimiento de imágenes, `content` puede ser un array que contenga texto y la `image_url` (Base64).
tools	array	Sí	Una lista de herramientas a las que el modelo puede llamar. Actualmente, solo se admiten funciones como herramientas. Se utiliza para proporcionar una lista de funciones para las que el modelo puede generar una entrada JSON.
tool_choice	object	Sí	Controla qué función llama el modelo. `none` significa que no llamará a ninguna; `auto` significa selección automática; también se puede forzar la llamada a una función específica.
temperature	integer	No	Temperatura de muestreo, entre 0 y 2. Los valores más altos (ej. 0.8) hacen que la salida sea más aleatoria, mientras que los valores más bajos (ej. 0.2) la hacen más determinista. Se recomienda no modificar junto con `top_p`.
top_p	integer	No	Parámetro de muestreo de núcleo (nucleus sampling). 0.1 significa que solo se consideran los tokens que componen el 10% superior de la masa de probabilidad. Se recomienda no modificar junto con `temperature`.
n	integer	No	Cuántas opciones de completación de chat generar para cada mensaje de entrada. Por defecto es 1.
stream	boolean	No	Interruptor de salida en streaming. Por defecto es `false`. Si se establece en `true`, se enviarán fragmentos de mensajes parciales como Eventos Enviados por el Servidor (SSE) y terminará con `data: [DONE]`.
stop	string	No	Secuencias (hasta 4) donde la API dejará de generar más tokens. Por defecto es null.
max_tokens	integer	No	El número máximo de tokens a generar en la completación del chat. Por defecto es inf (infinito).
presence_penalty	number	No	Penalización por presencia (entre -2.0 y 2.0). Los valores positivos penalizan los nuevos tokens en función de si ya han aparecido en el texto, aumentando la probabilidad de que el modelo hable sobre nuevos temas.
frequency_penalty	number	No	Penalización por frecuencia (entre -2.0 y 2.0). Los valores positivos penalizan los nuevos tokens en función de su frecuencia actual en el texto, disminuyendo la probabilidad de que el modelo repita el mismo contenido. Por defecto es 0.
logit_bias	object	No	Modifica la probabilidad de que aparezcan tokens específicos en la completación. Acepta un objeto JSON que mapea los IDs de los tokens a valores de sesgo (de -100 a 100).
user	string	No	Un identificador único que representa a su usuario final, lo que ayuda a monitorear y detectar abusos.
response_format	object	No	Especifica el formato que el modelo debe emitir. Pasar `{ "type": "json_object" }` habilita el modo JSON. Al usarlo, debe instruir al modelo a emitir JSON a través del prompt.
seen	integer	No	Función Beta. Semilla de muestreo determinista. Repetir solicitudes con la misma semilla y parámetros debería devolver el mismo resultado (el determinismo absoluto no está garantizado).

Ejemplo de Solicitud

{
  "model": "gpt-4o-mini",
  "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": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiEAAAIhCAYAAACYF2qHAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR4nOy9ebxtWVXf+x1zrrX2Pud2VRQUjUVf0glIYvOJLdJ8iCagIor... (se omite la cadena base64 demasiado larga)"
          }
        }
      ]
    }
  ]
}

Parámetros de Respuesta (Response Body)

Nombre del Campo	Tipo	Descripción
id	string	Identificador único para la completación del chat.
object	string	Tipo de objeto, generalmente `chat.completion` (o `chat.completion.chunk` en caso de streaming).
created	integer	Marca de tiempo Unix de la creación.
choices	array	Lista de opciones de completación.
└─ index	integer	Índice de la opción en la lista.
└─ message	object	Objeto del mensaje generado por el modelo, contiene `role` y `content`.
└─ finish_reason	string	Razón por la cual el modelo dejó de generar (ej. `stop` significa finalización normal, `length` significa que se alcanzó el límite de `max_tokens`).
usage	object	Estadísticas de consumo de tokens para esta solicitud.
└─ prompt_tokens	integer	Número de tokens consumidos por el prompt (incluyendo los tokens calculados para la imagen).
└─ completion_tokens	integer	Número de tokens consumidos por el contenido generado.
└─ total_tokens	integer	Número total de tokens consumidos en esta solicitud.

Ejemplo de Respuesta (Éxito 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
    }
}

Preguntas Frecuentes (FAQs)

P1: ¿Cómo activar la salida en streaming (Streaming)? R: Establezca el parámetro stream en true en el cuerpo de la solicitud. Una vez activado, el endpoint ya no esperará a que se genere toda la respuesta antes de devolverla, sino que devolverá fragmentos de datos en formato data: {...} palabra por palabra / frase por frase a través de Eventos Enviados por el Servidor (Server-Sent Events, SSE) hasta que reciba la marca data: [DONE] que indica el fin de la generación.

P2: ¿Cuáles son los requisitos para la codificación Base64 en el reconocimiento de imágenes? R: La cadena Base64 de la imagen debe contener el prefijo del tipo MIME correcto, por ejemplo, data:image/png;base64, o data:image/jpeg;base64,. Se recomienda comprimir adecuadamente el tamaño de la imagen antes de convertirla a Base64 para reducir la latencia de transmisión de la red y el consumo de prompt_tokens (las imágenes demasiado grandes consumirán una gran cantidad de tokens e incluso pueden exceder el límite de contexto).

P3: ¿Por qué se truncó la respuesta del modelo? R: Verifique el valor de choices[0].finish_reason en el cuerpo de la respuesta. Si es length, significa que el texto generado alcanzó el límite de max_tokens que ha establecido, o que toda la conversación superó el límite máximo de la ventana de contexto del modelo. Puede solucionar este problema aumentando el valor de max_tokens.

P4: ¿Cómo forzar al modelo a emitir datos en formato JSON? R: Primero, debe establecer "response_format": { "type": "json_object" } en el cuerpo de la solicitud. Aviso importante: Además de configurar este parámetro, también debe indicar explícitamente al modelo en lenguaje natural que emita JSON en el prompt del sistema (system prompt) o del usuario en messages (por ejemplo: "Por favor, devuelve los resultados en formato JSON"). Si no hace esto, el modelo podría entrar en un bucle infinito de generación en blanco hasta agotar todos los tokens.

P5: ¿Qué debo hacer si me encuentro con un error 401 Unauthorized? R: Verifique si el parámetro Authorization en los encabezados de la solicitud contiene correctamente la clave de la API (API Key). El formato debe ser estrictamente Bearer TU_API_KEY (note que hay un espacio obligatorio entre Bearer y la clave).