Chatbox es un cliente de IA multiplataforma, disponible para escritorio y móvil, que también puede conectarse a varios proveedores de modelos. Tiene dos usos típicos: utilizar el servicio integrado Chatbox AI o aportar tu propia API Key para conectarte a tus modelos. Este artículo solo trata el segundo caso: cómo conectar Chatbox a una API personalizada compatible con OpenAI.
Nota: Chatbox es un producto de su titular; este artículo solo ofrece una explicación técnica de integración. Los nombres de los menús y la posición de los campos pueden cambiar según la versión; toma como referencia la versión actual. Los modelos y precios se indican en los precios de modelos del sitio.
1. Decide primero qué modo vas a usar
| Modo | Facturación | Dónde se configura | Para quién |
|---|---|---|---|
| Chatbox AI | Según el plan del cliente | Basta con iniciar sesión | Usuarios que no quieren gestionar claves |
| API Key propia | El proveedor de API cobra por uso | Ajustes del proveedor de modelos | Equipos que ya tienen un gateway o una cuenta de modelos |
| Modelo local | Depende del hardware del equipo | Servicio de inferencia local | Casos en los que los datos no deben salir del equipo |
Los dos modos pueden coexistir. Se recomienda dar un nombre propio al proveedor personalizado, por ejemplo «ZSQH», para no confundirlo con el servicio integrado. Al cambiar de modelo, comprueba primero qué proveedor está usando la conversación actual.
2. Prepara tres parámetros
- Clave de API: créala en ZSQH AI Gateway y ponle un nombre por proyecto.
- Host de API: dirección compatible con OpenAI, habitualmente
https://ai.zhongshangqihang.com/v1. - ID del modelo: copia el identificador de API exacto de la página de precios de modelos.
Verifica primero con curl para descartar problemas del lado del gateway:
export ZSQH_API_KEY="sk-tu-clave"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $ZSQH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tu-modelo-id",
"messages": [{"role": "user", "content": "Responde solo OK"}]
}'
Si devuelve choices, la clave, la dirección y el modelo son válidos y solo queda la operación en el cliente.
3. Añadir un proveedor de modelos personalizado
Con las versiones habituales actuales, los pasos son los siguientes (el texto exacto de los botones depende de tu versión):
- Abre Chatbox y pulsa «Settings» en la esquina inferior izquierda.
- En el panel izquierdo, selecciona «Model Providers» y pulsa «+ Add» en la parte inferior.
- Pon al proveedor un nombre fácil de reconocer.
- Selecciona el modo de API compatible con OpenAI o la opción OpenAI correspondiente.
- Introduce la clave de API y el host de API.
- Pulsa «Fetch» para obtener la lista de modelos o añade manualmente el ID del modelo.
- Pulsa «Check» para probar la conexión y selecciona el modelo que acabas de añadir.
Si «Fetch» falla, no significa necesariamente que la clave tenga un problema; puede que el gateway no exponga la interfaz de lista de modelos. En ese caso, introduce el ID del modelo manualmente y valida con «Check».
4. Host de API y /v1
La Base URL es el campo que más errores provoca en una API personalizada. Compruébala con esta tabla:
| Elemento | Valor recomendado | Atención |
|---|---|---|
| Modo de API | Compatible con OpenAI | No elijas el modo Anthropic ni Gemini |
| Host de API | https://ai.zhongshangqihang.com/v1 |
Sin barra al final |
| Clave de API | sk-... |
Sin espacios delante ni detrás |
| ID del modelo | Según la página de precios | Distingue mayúsculas y sufijos de versión |
Si con la dirección completa obtienes 404, prueba a quitar /v1; si con el dominio obtienes 404, añade /v1. Cada versión del cliente concatena las rutas de forma distinta; guíate por el resultado real de la solicitud. Ante un 401, revisa primero la clave; ante un 404, revisa primero la ruta. Este orden ahorra mucho tiempo.
5. ID del modelo y configuración de capacidades
Al añadir un modelo manualmente, normalmente también hay que elegir el tipo de modelo y sus capacidades. Las correspondencias habituales son:
| Tipo de modelo | Uso | Capacidades que hay que marcar |
|---|---|---|
| Modelo de chat | Preguntas, redacción, traducción | Texto, salida en streaming |
| Modelo de razonamiento | Análisis complejo, planificación | Razonamiento o proceso de pensamiento |
| Modelo de visión | Comprensión de imágenes, preguntas sobre capturas | Entrada de imágenes |
| Modelo de herramientas | Llamadas a funciones, plugins | Llamadas a herramientas |
Si eliges mal el tipo de modelo, puede que no aparezca en el selector de chat; si no marcas una capacidad, fallarán la subida de imágenes o las llamadas a herramientas. Si no estás seguro, configura primero solo chat de texto y añade capacidades una a una cuando funcione.
6. Verificar la conexión
La opción «Check» del cliente suele probar por separado el texto, las imágenes y las llamadas a herramientas. Como mínimo, confirma que la solicitud de texto funciona. Lo más fiable es enviar una pregunta real y observar tres cosas:
- Si el primer token llega con normalidad o si la rueda de carga se queda girando.
- Si la conversación de varios turnos conserva el contexto.
- Si las respuestas largas se cortan a mitad.
Si solo se cortan las respuestas largas, revisa primero el proxy de red y las respuestas en streaming; si fallan todas las solicitudes, vuelve a la clave y a la Base URL. También puedes abrir un software de proxy en el equipo para comparar, pero no pongas la dirección del proxy en el host de API.
7. Errores habituales y cómo resolverlos
| Síntoma | Causa habitual | Solución |
|---|---|---|
401 Unauthorized |
Clave incorrecta, caducada o eliminada | Crea una clave nueva y confirma que no tiene espacios |
404 Not Found |
Ruta del host de API incorrecta | Añade o quita /v1 y vuelve a intentarlo |
model not found |
ID del modelo incorrecto o no habilitado | Cópialo de la página de precios |
| Tiempo de conexión agotado | Red inaccesible o proxy que bloquea | Cambia de red y revisa el firewall |
| La respuesta se detiene a mitad | Conexión de streaming interrumpida | Desactiva la salida en streaming y compara |
429 Too Many Requests |
Límite de concurrencia o de cuota | Reduce la concurrencia y consulta el uso del gateway |
| Error al subir imágenes | El modelo no admite visión o falta marcar la capacidad | Cambia a un modelo de visión y marca la entrada de imágenes |
Al solucionar problemas, cambia solo una variable a la vez. Si cambias al mismo tiempo la clave, la dirección y el modelo, aunque vuelva a funcionar no sabrás qué paso lo arregló y volverás a tropezar la próxima vez.
8. Seguridad y costes
- Tanto la versión móvil como la de escritorio pueden guardar la clave; ten cuidado en equipos compartidos.
- Emite una clave independiente para Chatbox, así podrás revocarla en cualquier momento.
- Configura un límite de presupuesto en el gateway para evitar que una sesión abierta mucho tiempo consuma cuota.
- No pegues claves de producción, listas de clientes ni contratos originales en las conversaciones.
- Exporta o haz copia de seguridad de las conversaciones importantes con regularidad; desinstalar el cliente no equivale a tener una copia en la nube.
- Si el equipo comparte el cliente, emite una clave por persona para poder desglosar el uso.
Preguntas frecuentes
¿Chatbox con API Key propia sigue cobrando una suscripción?
En el modo de clave propia, el coste de las llamadas a los modelos lo cobra el proveedor de API por uso; la forma de cobro del cliente Chatbox depende de la versión actual. No conviene mezclar ambas cosas.
¿Por qué falla siempre «Fetch models»?
Puede que el gateway no exponga la interfaz de lista de modelos o que la ruta de la Base URL no sea correcta. Añade primero un ID de modelo manualmente para probar; si la adición manual funciona, significa que solo falta el soporte de la interfaz de lista.
¿Hay que añadir /v1 al host de API?
La mayoría de las configuraciones compatibles con OpenAI necesitan /v1. Si falla tanto con como sin él, confirma primero con curl la dirección completa correcta de la solicitud y luego cópiala en el cliente; no lo dejes a la suerte.
¿Se pueden configurar varios proveedores a la vez?
Sí. Da un nombre distinto a cada proveedor y elige explícitamente el modelo en cada conversación. Cuando conviven varios proveedores, el error más frecuente es creer que estás usando A cuando la solicitud se envía a B.
¿Se puede usar directamente en el móvil?
Puedes instalar la versión móvil y configurar un proveedor personalizado, pero los accesos y las capacidades disponibles pueden variar según la plataforma; toma como referencia la versión actual. No se recomienda guardar claves sensibles en el móvil durante largos periodos.
Próximos pasos
La configuración de Chatbox tiene solo tres puntos clave: host de API, clave e ID del modelo. Prueba primero con curl y después pasa al cliente; si falla, revisa la clave ante 401, la ruta ante 404 y el ID del modelo ante model not found. Si necesitas un punto de acceso unificado y gestión de uso, puedes registrarte en ZSQH AI Gateway; los modelos y precios se indican en la página de precios de modelos.
Lecturas relacionadas:
