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

Esta API admite entrada multimodal, permitiendo a los usuarios enviar texto y URLs de imágenes dentro de la conversación. El modelo generará respuestas correspondientes basadas en el prompt de entrada y el contenido de la imagen. Soporta salida en flujo (Streaming) para proporcionar una experiencia de interacción mucho más fluida.

• Dirección de la API (Endpoint): https://api.codingplanx.ai/v1/chat/completions
• Método de la solicitud: POST
• Referencia oficial: OpenAI Chat Completion API

---

Parámetros de la Solicitud

Parámetros del Header

Parámetros del Body

Estructura del objeto messages

Cada elemento en la lista de mensajes contiene los siguientes campos:

• role: (string) Rol, opciones disponibles: system, user, assistant, tool.
• content: (string o array) Contenido del mensaje.
  • En modo de reconocimiento de imágenes, content es un array que contiene objetos de tipo text y image_url.

---

Ejemplo de Solicitud

Solicitud mixta de Texto e Imagen (JSON)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Eres un asistente profesional de análisis de imágenes."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "¿Qué hay en esta imagen? Por favor, descríbelo en detalle."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

---

Explicación de la Respuesta

Respuesta No Streaming (stream: false)

Ejemplo de Respuesta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Esta imagen muestra un lago tranquilo con montañas ondulantes al fondo."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

Respuesta en Streaming (stream: true)

Cuando stream es true, la API devuelve un text/event-stream. Cada línea comienza con data: , y el contenido es una cadena JSON. El último mensaje devuelto será data: [DONE].

---

FAQs (Preguntas Frecuentes)

Q1: ¿Cómo puedo implementar la subida de una imagen en lugar de proporcionar una URL? R: Esta API admite principalmente URLs de imágenes. Si solo tienes imágenes locales, te recomendamos subirlas primero a tu servicio de alojamiento de imágenes o almacenamiento de objetos (OSS), o convertir la imagen a una cadena codificada en Base64 con el formato data:image/jpeg;base64,{base64_encode_data} e introducirla en el campo url.

Q2: ¿Por qué mi solicitud en streaming no devuelve las estadísticas de uso (usage)? R: En el protocolo estándar de streaming compatible con OpenAI, el usage normalmente solo se devuelve en el último fragmento de datos o configurando un parámetro especial llamado stream_options. Por favor, verifica si la versión de tu modelo soporta devolver el conteo de tokens dentro del flujo (stream).

Q3: ¿Cuáles son los límites de tamaño y formato para el reconocimiento de imágenes? R: Por lo general, se admiten los formatos PNG, JPEG, WEBP y GIF (no animados). Se recomienda que el tamaño de la imagen no supere los 20MB. Para obtener los mejores resultados de reconocimiento, sugerimos una resolución superior a 512x512.

Q4: ¿Qué debo hacer si mi solicitud devuelve el error "401 Unauthorized"? R: Asegúrate de haber pasado correctamente el campo Authorization en el Header, utilizando el formato Bearer seguido de tu API KEY, y verifica que la clave sea válida y tenga saldo o cuota suficiente.

Q5: ¿El parámetro temperature afecta al reconocimiento de imágenes? R: Sí. El parámetro temperature influye en la creatividad lingüística del modelo al describir la imagen. Si necesitas una descripción muy objetiva y rigurosa, te recomendamos establecer un valor bajo (ej. 0.2); si prefieres una descripción más vívida y entretenida, puedes configurarlo con un valor más alto (ej. 0.8).

Q6: ¿Cómo puedo procesar el reconocimiento de múltiples imágenes a la vez? R: Puedes añadir múltiples objetos de tipo image_url dentro del array messages.content. El modelo intentará comprender el contenido de todas esas imágenes simultáneamente.