La key de una interfaz OCR es, en esencia, una credencial de identidad. Pero el uso de OCR tiene particularidades: se procesan facturas, documentos de identidad y escaneos por lotes, muchas veces en segundo plano. Si la key se filtra, otra persona consume tu cuota y lo que puede quedar expuesto son datos de tus clientes. Además, muchos equipos llevan la key de pruebas directamente a producción.

Este artículo sigue el orden real de integración: primero los tipos de key, luego el registro y la creación, después permisos, cuotas, variables de entorno, diagnóstico de errores 401 y la elección entre acceso directo y gateway. Al final, rotación y respuesta ante filtraciones.

Nota: OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud, Baidu y las demás marcas mencionadas son marcas registradas de sus respectivos titulares. Este artículo tiene fines técnicos y no implica afiliación con esos proveedores; las interfaces, los permisos y las reglas de facturación se rigen por la documentación oficial de cada plataforma y por las páginas de este sitio.

1. Primero, distingue los tres tipos de autenticación de OCR

Las keys de OCR no siguen un estándar único. Antes de integrarte, confirma a qué categoría pertenece la plataforma de destino; de lo contrario, es fácil terminar con un «la key es correcta, pero devuelve 401»:

  • Bearer key: la forma más común en interfaces compatibles con OpenAI. El encabezado es Authorization: Bearer sk-...; chat, visión y OCR suelen compartir la misma autenticación.
  • Access key + secret key: la usan algunos proveedores de nube. La solicitud debe firmarse según la documentación y el secret nunca debe escribirse en el frontend ni en los logs.
  • API key + secret key para obtener un token: primero se llama a la interfaz de autenticación con la key y el secret para obtener un access_token de corta duración; luego se usa ese token en las llamadas de OCR y se renueva al vencer.

En una misma plataforma, OCR también puede compartir una sola key con los modelos de chat. Poder llamar o no depende de los permisos de la cuenta, la autorización del modelo y el saldo, no del tipo de key. Antes de crear una, revisa si la consola admite una lista blanca de modelos o permisos de subcuenta.

2. Pasos para registrarse y crear la key

Tomemos como ejemplo ZSQH AI Gateway. El flujo es el siguiente:

  1. Abre https://ai.zhongshangqihang.com o usa directamente el enlace de registro, regístrate con tu correo y completa la verificación.
  2. Inicia sesión, entra a la consola y consulta las keys existentes en la página «Claves API».
  3. Ve a «Cartera» y confirma el saldo; durante las pruebas, carga primero un monto pequeño.
  4. Haz clic en «Crear clave», asigna un nombre, un límite de cuota y una fecha de vencimiento; si la plataforma lo permite, restringe los modelos disponibles.
  5. Copia la key completa inmediatamente después de guardarla. La mayoría de las plataformas solo la muestran una vez; al cerrar la página solo queda la versión enmascarada.
  6. Envía una solicitud con una imagen de prueba y luego revisa en «Registro de uso» que el modelo, el número de llamadas y el costo registrado sean correctos.

Si usas el OCR nativo de un proveedor de nube, se recomienda crear una subcuenta y otorgar solo los permisos relacionados con OCR; no utilices la access key de la cuenta principal para pruebas ni para producción.

3. Cómo completarla: nombre, cuota y vencimiento

El nombre de la key debe facilitar la revisión de facturas seis meses después. Conviene combinar «uso + entorno», por ejemplo ocr-prod-batch, ocr-staging u ocr-dev-zhang; evita nombres como «prueba1».

Define primero una cuota baja y auméntala después de confirmar el consumo de un lote real de imágenes. Ajusta el vencimiento según el uso: 7 o 30 días para scripts temporales, y un ciclo fijo de rotación también para las keys de producción. Una distribución práctica es la siguiente:

Escenario Nombre de la key Cuota Ubicación Rotación
Desarrollo local ocr-dev-nombre Nivel mínimo .env local 30 días
Entorno de pruebas ocr-staging Baja Secreto de CI/CD 60 días
Producción por lotes ocr-prod-batch Según presupuesto Gestor de secretos 90 días
Producción en tiempo real ocr-prod-realtime Según presupuesto Gestor de secretos 90 días

Si la plataforma permite limitar permisos por modelo, marca solo los modelos de OCR o visión que necesitas; si solo permite aislar por proyecto, al menos separa proyecto y cuota. No uses la misma key para depuración local, entorno de pruebas y producción.

4. Cuatro principios para diseñar permisos

  • Una key por uso: separa el reconocimiento por lotes, la interfaz en tiempo real y los scripts de administración. Si un tipo de tarea falla, puedes desactivar su key sin afectar a los demás.
  • Mínimo privilegio: si basta con OCR, no habilites todos los modelos; si puedes usar una subcuenta, no emitas una key de la cuenta principal; si puedes limitar el proyecto, no otorgues permisos a nivel de cuenta.
  • Nada de keys en el frontend: las keys en navegadores, apps y miniprogramas se extraen con facilidad. La carga de imágenes y las solicitudes de OCR deben pasar por tu propio backend, que es quien conserva la key.
  • Separación entre producción y pruebas: una filtración de la key de pruebas no afecta la factura de producción ni contamina los registros de uso reales.

El OCR suele trabajar con facturas, contratos y documentos de identidad. Los permisos de la key se parecen a los permisos de acceso a datos. Además de controlar quién puede llamar, confirma si la plataforma conserva las imágenes originales, durante cuánto tiempo y si las usa para entrenamiento. Si el entorno de producción admite listas blancas de IP, actívalas y conserva registros de auditoría.

5. La key en variables de entorno

No la escribas directamente en el código ni la confirmes en Git. En Python puedes leerla así:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model=os.environ["OCR_MODEL"],  # Modelo con entrada de imagen según la página de precios
    messages=[{"role": "user", "content": "Responde solo OK"}],
)
print(resp.choices[0].message.content)

Este código solo verifica que la key, la URL base y el nombre del modelo coincidan; cuando confirmes la conexión, cambia la solicitud por una imagen real.

Si usas un archivo .env local, agrégalo a .gitignore y confirma solo .env.example. En producción, prioriza secretos de contenedor, el gestor de secretos del proveedor de nube o un servicio como Vault; no escribas la key en el Dockerfile, en las capas de la imagen, en el bundle del frontend ni en los logs de CI. Después de modificar una variable de entorno, reinicia el proceso: muchos casos de «401 en producción, funciona en local» se deben a que el servicio sigue leyendo la variable anterior o a que la plataforma de despliegue no inyectó la variable en el entorno de ejecución.

6. Orden de diagnóstico de un 401

Si recibes 401 Unauthorized, revisa en este orden; normalmente el problema se localiza en pocos minutos:

  1. Verifica que el encabezado sea Authorization: Bearer sk-... y que haya un solo espacio entre Bearer y la key.
  2. Vuelve a copiar la key y confirma que no tenga espacios, saltos de línea, comillas ni caracteres invisibles.
  3. Confirma que la key no haya sido eliminada, deshabilitada o vencida.
  4. Confirma que la key y la URL base pertenezcan a la misma plataforma; no envíes una key de la plataforma A a la plataforma B.
  5. Imprime en el proceso la longitud de la variable de entorno (no su contenido) para confirmar que se leyó un valor y no una cadena vacía.
  6. Revisa si el proxy inverso, el gateway o el SDK reescribieron el encabezado Authorization; al subir formularios multipart es especialmente fácil perderlo.
  7. Si solo fallan algunas solicitudes, revisa si alguien expuso la key en el frontend y el sistema de riesgo la desactivó.

También conviene distinguir los tipos de error: 401 es un problema de identidad; 403 suele indicar permisos o restricciones regionales; 413 aparece cuando la imagen es demasiado grande; 429 suele ser un problema de frecuencia o cuota. En OCR, el 400 muchas veces corresponde al formato de imagen, a la codificación Base64 o a un archivo dañado; no lo atribuyas siempre a la key.

7. ¿Key oficial o key de gateway?

Ambas rutas funcionan; la diferencia principal está en la compra, la red y el mantenimiento:

  • Acceso directo oficial: la cuenta, la facturación y los modelos los gestiona el fabricante. Es adecuado para equipos que pueden pagar en la moneda del proveedor y resolver por su cuenta la red y el cumplimiento. Si usas un solo OCR, es el camino más corto; la desventaja es que cada proveedor autentica de forma distinta y, al integrar varios, hay que mantener varias keys y facturas.
  • Acceso por gateway: una URL base y una key para llamar a modelos de varios proveedores; el acceso desde China y el pago en yuanes resultan más sencillos, y los logs y límites quedan centralizados. El costo es una dependencia adicional: confirma la política de datos del proveedor, la disponibilidad, la forma de notificar incidentes y el soporte de facturas.

No elijas solo por precio. Confirma al menos: si se conservan las imágenes y los resultados, si se emiten facturas, si hay avisos cuando un modelo se retira, si puedes exportar el uso y cómo contactar al soporte durante una incidencia. Los modelos y precios concretos se rigen por lo que muestre Precios de modelos en ese momento; los precios cambian, así que no presupuestes con cifras de artículos antiguos.

8. Rotación y respuesta ante filtraciones

Conviene convertir la rotación en una tarea periódica, no en una reacción ante incidentes:

  1. Crea en la plataforma original una key nueva con los mismos permisos.
  2. Actualiza el valor en la variable de entorno o en el gestor de secretos.
  3. Reinicia o vuelve a desplegar el servicio y envía una imagen de prueba para confirmar que funciona.
  4. Observa el registro de uso durante 24 a 48 horas para descartar llamadas anómalas.
  5. Desactiva y elimina la key antigua, y registra la fecha de rotación y el responsable.

Si sospechas una filtración, invierte el orden: primero desactiva la key antigua, luego revisa el registro de uso y el origen de las llamadas, inspecciona el historial del repositorio, los logs de CI y las capas de la imagen, y por último crea la key nueva. Borrar la cadena del código no basta: la key pudo copiarse a otro lugar. Si la cuenta tiene saldo, evalúa también reducir la cuota de forma temporal.

Preguntas frecuentes

¿La key de OCR y la del modelo de chat son la misma?

En las plataformas compatibles con OpenAI suele ser la misma autenticación: una sola key puede llamar al chat y a los modelos de visión con entrada de imagen. Poder usarla depende de los permisos de la cuenta y de la autorización del modelo, no del tipo de key.

¿Se puede ver la key completa después de crearla?

Normalmente no. La key completa se muestra una sola vez al crearla; después solo queda la versión enmascarada. Si no la guardaste, elimínala y créala de nuevo; no intentes recuperarla de los logs ni de la caché del navegador.

¿Por qué funciona en local pero el servidor devuelve 401?

Revisa primero tres cosas: si la variable de entorno se inyectó, si el proxy inverso conserva el encabezado Authorization y si en producción se usa una key eliminada o vencida. Después confirma que la URL base apunte a la plataforma correcta.

¿El OCR se cobra por imagen o por token?

Ambos modelos existen. El OCR tradicional suele cobrar por imagen o por página; los modelos multimodales suelen cobrar por los tokens de entrada que representan las imágenes más los tokens de salida. Las reglas concretas se rigen por la documentación de la plataforma y por Precios de modelos.

¿Basta con eliminar la key si se filtró?

No. Primero desactiva la key, luego revisa el registro de uso para confirmar si hubo llamadas anómalas, inspecciona el repositorio, los logs de CI y el historial de imágenes, y por último rota todas las keys que puedan estar afectadas. Si hay documentos de identidad o facturas de clientes involucrados, evalúa según tu procedimiento interno de seguridad si corresponde notificar.

Próximos pasos

Si aún no tienes cuenta, empieza por la página de registro, crea una key con cuota baja y valida la autenticación con una imagen de prueba. Cuando funcione, consulta Precios de modelos para elegir el modelo definitivo. El tratamiento de campos estructurados se explica en la guía de integración.

Lecturas relacionadas: