Obtener una clave de API de OpenAI es fácil. Diseñar un acceso a la API de OpenAI que siga siendo seguro, testeable y reemplazable a medida que tu producto añade más modelos es el verdadero trabajo de ingeniería.
Para un prototipo, una clave personal y una sola llamada al modelo pueden ser suficientes. Un producto multimodelo en producción necesita una configuración distinta: credenciales con ámbito de proyecto, entornos separados, comprobaciones explícitas de endpoints y capacidades, manejo de límites de velocidad, visibilidad del uso y una vía controlada para introducir proveedores de respaldo.
Esta guía convierte esos requisitos en una lista de verificación de implementación. Primero cubre el acceso directo a OpenAI y luego muestra dónde una pasarela compatible con OpenAI puede reducir el trabajo operativo cuando tu producto se expande más allá de un proveedor.
Verificado el 28 de julio de 2026: La guía actual de la plataforma de OpenAI centra el desarrollo de API en proyectos, admite cuentas de servicio de proyecto y permisos de clave restringidos, recomienda un manejo seguro de claves del lado del servidor y posiciona la API Responses como la interfaz principal para nuevos flujos de trabajo agénticos y multimodales. Verifica el acceso y los límites actuales de los modelos en tu propia cuenta antes de la implementación en producción.
The Short Version
Usa esta secuencia para un nuevo producto multimodelo:
- Crea proyectos separados de OpenAI para desarrollo, staging y producción.
- Usa una cuenta de servicio del proyecto o una clave de proyecto con ámbito estricto para las cargas de trabajo del servidor.
- Mantén los secretos en el servidor y fuera del control de código fuente, navegadores y aplicaciones móviles.
- Elige la API Responses o Chat Completions según las funciones que tu aplicación realmente use.
- Prueba por separado la disponibilidad del modelo, las salidas estructuradas, las herramientas, el streaming y las entradas multimodales.
- Mide los límites de velocidad, timeouts, reintentos, latencia y coste por tarea exitosa.
- Coloca la URL base del proveedor, la clave y el modelo detrás de la configuración.
- Añade un segundo proveedor solo después de tener un conjunto de evaluación compartido y una ruta de reversión.
El objetivo no es solo hacer una solicitud exitosa. Es hacer que el acceso sea gobernable y portátil.
What OpenAI API Access Means in Production
El acceso en producción tiene seis capas. Si alguna capa permanece implícita, normalmente se convierte en un incidente más adelante.
| Access layer | Production question | Evidence to capture |
|---|---|---|
| Organization and project | Which environment and team owns the workload? | Project ID, owner, environment, budget owner |
| Credential | Which machine or service may call the API? | Service account or project key, permission scope, rotation owner |
| Endpoint | Which API interface does the application depend on? | Responses, Chat Completions, Realtime, embeddings, image, or other endpoint |
| Model | Which capabilities and limits does the task require? | Model ID, tool support, modalities, context needs, output contract |
| Operations | What happens under load or partial failure? | Rate-limit test, retry policy, timeout, queue behavior, request IDs |
| Portability | How quickly can the workload move or fall back? | Config switch, compatibility test, evaluation score, rollback procedure |
Esta matriz de acceso es más útil que una lista de claves API. Vincula cada credencial a una carga de trabajo, cada carga de trabajo a un contrato y cada contrato a un plan operativo.
Step 1: Separate Projects by Environment
Los proyectos de OpenAI proporcionan un límite para las claves API, las cuentas de servicio, el uso, el acceso a modelos, los límites de tasa y los presupuestos. Eso convierte a los proyectos en el punto de partida adecuado para separar desarrollo, pruebas y producción.
Una estructura práctica es:
| Project | Typical users | Credential type | Main purpose |
|---|---|---|---|
| Development | Individual engineers and CI test jobs | Personal project keys or restricted automation keys | Local development and low-risk experiments |
| Staging | CI/CD and pre-production services | Project service account | Load tests, integration tests, release candidates |
| Production | Deployed backend services only | Project service account with minimum permissions | Customer traffic |
No compartas una única clave de producción entre portátiles, CI, staging y múltiples servicios. Las credenciales compartidas hacen que la rotación sea disruptiva y dificultan atribuir usos inesperados.
La documentación de OpenAI describe las cuentas de servicio del proyecto como identidades con alcance a nivel de proyecto. Cuando se crea una cuenta de servicio, su secreto se muestra una sola vez, así que guárdalo de inmediato en tu gestor de secretos. OpenAI también admite permisos de clave como All, Restricted y Read Only; usa los permisos más محدودidos compatibles con la carga de trabajo.
Step 2: Keep API Keys Server-Side
Una clave API de OpenAI es un secreto, no un identificador de aplicación. Nunca la expongas en JavaScript del navegador, paquetes de aplicaciones móviles, repositorios públicos, registros del lado del cliente ni capturas de pantalla de soporte.
Usa variables de entorno o un almacén de secretos administrado:
OPENAI_API_KEY="your-project-or-service-account-key"
OPENAI_MODEL="your-validated-model-id"
OPENAI_BASE_URL="https://api.openai.com/v1"
Luego crea el cliente en un único módulo del lado del servidor:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
La URL base debe ir en la configuración incluso si hoy solo usas OpenAI. Esa pequeña decisión facilita probar proxies de staging, infraestructura regional y enrutamiento compatible con OpenAI en el futuro sin editar cada punto de llamada.
Minimum key-management policy
- Assign an owner for each production credential.
- Record the service and environment that use it.
- Store it in a secrets manager, not a shared document.
- Rotate it on a schedule and immediately after suspected exposure.
- Remove unused keys and former team members' access.
- Alert on unexpected usage and spend changes.
- Avoid embedding keys in images, tickets, analytics events, or application errors.
La guía de seguridad de claves de OpenAI también recomienda nunca confirmar claves en un repositorio y usar variables de entorno en lugar de codificarlas directamente.
Step 3: Choose the API Interface Before the Model
La selección de modelo recibe la mayor parte de la atención, pero la elección del endpoint suele generar el mayor coste de migración.
La documentación actual de OpenAI recomienda la Responses API para nuevos proyectos que necesitan herramientas integradas, entradas multimodales o flujos de trabajo tipo agente. Chat Completions sigue siendo útil cuando tu aplicación ya tiene una integración estable basada en mensajes o necesita amplia compatibilidad con clientes y gateways estilo OpenAI.
| Requirement | Start with | Migration note |
|---|---|---|
| New agentic workflow | Responses API | Validate tool behavior, state handling, and output contracts |
| Built-in OpenAI tools | Responses API | Confirm the selected model and account support each tool |
Existing messages integration |
Chat Completions | Keep if it is stable; migrate for a specific capability, not fashion |
| Cross-provider client portability | Chat Completions or a tested compatibility layer | Compatibility varies by provider and parameter |
| Low-latency speech interaction | Realtime API | Treat transport, session lifecycle, and audio handling as separate tests |
| Embeddings, image, or other modality-specific work | Relevant endpoint | Do not assume a chat smoke test proves another endpoint |
Una arquitectura multimodelo puede usar más de una interfaz. La regla importante es definir explícitamente el contrato de cada carga de trabajo en lugar de ocultar comportamientos incompatibles detrás de una única función genérica generate().
Step 4: Run an Access Smoke Test
Empieza con la solicitud del lado del servidor más pequeña que demuestre autenticación, acceso al endpoint y acceso al modelo.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
response = client.responses.create(
model=os.environ["OPENAI_MODEL"],
input="Return exactly: access-ok",
)
print(response.output_text)
Para un cliente existente de Chat Completions:
response = client.chat.completions.create(
model=os.environ["OPENAI_MODEL"],
messages=[
{"role": "user", "content": "Return exactly: access-ok"}
],
)
print(response.choices[0].message.content)
No trates esto como la prueba de integración completa. Solo demuestra una ruta limitada.
Registra:
- Estado HTTP y resultado de aplicación normalizado
- ID de modelo solicitado e ID de modelo devuelto, cuando esté disponible
- ID de solicitud o identificador de seguimiento
- Latencia y tiempo de espera
- Uso de entrada y salida
- Proyecto y entorno
- Versión del SDK
- Número de reintentos
Step 5: Build a Capability Test Matrix
Los nombres de los modelos cambian más rápido que los requisitos de producción. Prueba capacidades, no etiquetas de marketing.
Crea una fila por carga de trabajo:
| Carga de trabajo | Capacidad requerida | Condición de aprobación | Comportamiento de fallo o alternativa |
|---|---|---|---|
| Clasificación de soporte | Salida estructurada | Esquema válido en tickets representativos | Reintentar una vez y luego poner en cola para revisión |
| Asistente de investigación | Uso de herramientas y citas | Invocación correcta de herramientas y asignación de fuentes | Usar respuesta alternativa sin búsqueda |
| Extracción de documentos | Entrada de archivo o imagen | Los campos requeridos cumplen el umbral de precisión | Derivar a un modelo de visión más potente |
| Chat con clientes | Streaming | El primer token y la respuesta completa cumplen el SLO de latencia | Cambiar a un modelo sin streaming o de respaldo |
| Generación de código | Contexto largo y cumplimiento de instrucciones | La suite de pruebas pasa | Escalar a un modelo de mayor calidad |
Para cada modelo candidato, prueba el mismo conjunto de prompts y las mismas reglas de evaluación. Incluye entradas mal formadas, contexto vacío, contexto largo, timeouts y errores del proveedor. Un prompt de demostración exitoso no prueba la compatibilidad con producción.
Las métricas útiles incluyen:
- tasa de éxito de tareas
- tasa de respuestas válidas según el esquema
- tasa de éxito de llamadas a herramientas
- latencia p50 y p95
- tasa de reintentos
- coste por tarea exitosa
- tasa de escalado a un humano
Este es el puente entre el acceso a la API de OpenAI y el enrutamiento multimodelo: el enrutamiento debe seguir el rendimiento medido de la carga de trabajo, no una preferencia estática de proveedor.
Step 6: Planifica los límites de tasa y los niveles de uso
Los límites de tasa de OpenAI pueden aplicarse en dimensiones como solicitudes y tokens, y los límites varían según el modelo y el nivel de la cuenta. Consulta la página de límites actual para tu organización y modelo antes de configurar la concurrencia en producción.
Tu cliente debería distinguir al menos cuatro clases de fallo:
| Clase de fallo | Respuesta típica | Acción correcta |
|---|---|---|
| Autenticación o permisos | 401 o 403 | Detener los reintentos, revisar el proyecto, la clave y el alcance de permisos |
| Límite de tasa | 429 | Reducir la carga con jitter, disminuir la concurrencia o poner el trabajo en cola |
| Fallo del proveedor/servidor | 5xx | Reintentar un número limitado de veces y luego usar una alternativa o poner en cola |
| Solicitud no válida | 4xx | Corregir la solicitud; no crear una tormenta de reintentos |
Usa retroceso exponencial con jitter y un número máximo de intentos. Establece un presupuesto de tiempo total para toda la operación, no solo para cada llamada HTTP. De lo contrario, tres reintentos largos pueden superar el objetivo de nivel de servicio orientado al usuario.
Para trabajos asíncronos o aptos para lotes, una cola puede absorber límites temporales. Para trabajos interactivos, un modelo alternativo validado puede ser mejor. Esos son modos de operación distintos y deben tener políticas de reintento diferentes.
Step 7: Diseña la frontera multimodelo
Hay dos formas comunes de añadir más modelos.
Option A: Integraciones directas con proveedores
Usa SDK nativos y credenciales separados para cada proveedor.
Esto encaja bien cuando:
- necesitas funciones específicas del proveedor de inmediato;
- tu equipo puede gestionar varias cuentas de facturación y credenciales;
- quieres el acceso más temprano a las capacidades nativas de cada proveedor;
- estás preparado para normalizar por tu cuenta los errores, el uso, los reintentos y la telemetría.
Option B: Un gateway compatible con OpenAI
Usa una única URL base compatible y selecciona modelos mediante configuración o política de enrutamiento.
Esto encaja bien cuando:
- varias cargas de trabajo comparten el patrón de cliente de OpenAI;
- quieres una sola capa de acceso, facturación, cuota y uso;
- necesitas una evaluación de modelos más rápida y experimentos de fallback;
- la gestión de cuentas de proveedores se está convirtiendo en una carga operativa.
Flatkey proporciona una URL base compatible con OpenAI en https://router.flatkey.ai/v1. Con una carga de trabajo compatible, el límite del cliente puede permanecer estable mientras la clave, la URL base y el modelo pasan a la configuración.
FLATKEY_API_KEY="your-flatkey-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="your-validated-flatkey-model-id"
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ["OPENAI_BASE_URL"],
)
“Compatible con OpenAI” no significa que todos los endpoints y parámetros se comporten de forma idéntica. Vuelve a ejecutar la matriz de capacidades para streaming, salidas estructuradas, herramientas, entradas multimodales, respuestas de error, campos de uso y timeouts antes de cambiar el tráfico de producción.
Para una secuencia de migración práctica, usa la lista de verificación de migración del gateway API compatible con OpenAI. Para pruebas a nivel de modelo, usa el flujo de trabajo de pruebas de prompts multimodelo.
Step 8: Despliega con staging, pruebas sombra y canarios
Usa un despliegue por etapas incluso cuando la nueva ruta pase todas las evaluaciones offline.
- Staging: ejecuta tráfico representativo con concurrencia y timeouts similares a producción.
- Sombra: copia las solicitudes elegibles a la ruta candidata sin usar su respuesta para el cliente.
- Canario: envía un pequeño porcentaje del tráfico en vivo a la candidata.
- Expandir: aumenta el tráfico solo cuando la tasa de éxito, la latencia y el costo se mantengan dentro de los umbrales.
- Rollback: restaura la clave, la URL base y el modelo anteriores mediante configuración.
Define los umbrales de rollback antes del lanzamiento. Algunos ejemplos son:
- la tasa válida según el esquema cae por debajo de la línea base;
- la latencia p95 supera el SLO de la carga de trabajo;
- la tasa de reintentos o la tasa de 429 supera el límite acordado;
- la tasa de éxito de la tarea disminuye en un segmento de clientes protegido;
- el costo por tarea exitosa supera el umbral del presupuesto;
- falla una herramienta o modalidad requerida.
El rollback debe poder ejecutarlo el ingeniero de guardia sin un despliegue de código.
Lista de verificación de acceso a la API de OpenAI lista para producción
Identidad y secretos
- Desarrollo, staging y producción usan proyectos separados o límites equivalentes.
- Producción usa una cuenta de servicio del proyecto o una clave de proyecto con el mínimo alcance.
- Los secretos se almacenan del lado del servidor en un gestor de secretos.
- El propietario de la clave, el servicio, el entorno, la fecha de creación y el proceso de rotación están documentados.
- Las claves no aparecen en repositorios, bundles del navegador, aplicaciones móviles, registros ni tickets.
Contrato de la API
- La elección del endpoint está documentada por carga de trabajo.
- El acceso al modelo actual se verifica en el proyecto de destino.
- Las herramientas, modalidades, salidas estructuradas y streaming requeridos se prueban de forma independiente.
- El comportamiento del SDK y de la API se fija o registra para garantizar la reproducibilidad.
- Los campos específicos del proveedor se aíslan de la lógica compartida de la aplicación.
Fiabilidad y coste
- Se prueba el comportamiento ante 401/403, 429, 4xx, 5xx y timeouts.
- Los reintentos usan backoff exponencial, jitter, límites de intentos y un presupuesto total de tiempo.
- El uso, la latencia, los IDs de solicitud, los errores y el coste son observables.
- La concurrencia se ha probado contra los límites actuales del proyecto.
- El coste se mide por tarea exitosa, no solo por token.
Preparación multimodelo
- La URL base, la clave de API y el modelo son valores de configuración.
- Los modelos candidatos usan un único conjunto de evaluación representativo.
- Las reglas de fallback son específicas de la carga de trabajo.
- Los procedimientos de staging, shadow, canary y rollback están documentados.
- La compatibilidad del gateway se prueba para cada función requerida.
Preguntas comunes
¿Necesito una cuenta de OpenAI para cada desarrollador?
Se puede añadir a los desarrolladores a la organización y al proyecto pertinentes con los roles apropiados. Las cargas de trabajo de producción deberían usar una cuenta de servicio dedicada del proyecto o una credencial del proyecto en lugar de la clave personal de una persona.
¿Debería un producto multimodelo usar la API Responses o Chat Completions?
Usa la API Responses para nuevos flujos de trabajo nativos de OpenAI que necesiten funciones agénticas, herramientas integradas o comportamiento multimodal. Mantén Chat Completions cuando encaje con un contrato estable existente o cuando la portabilidad compatible con OpenAI sea una prioridad. En cualquier caso, prueba las capacidades exactas que necesites.
¿Puedo poner una clave de API de OpenAI en una aplicación frontend?
No. Redirige las solicitudes a través de tu backend para que la clave siga siendo secreta y puedas aplicar autenticación, cuotas, registro y controles contra abusos.
¿Una llamada exitosa a la API demuestra acceso de producción?
No. Solo demuestra que una clave, un endpoint, un modelo y una solicitud funcionaron una vez. La preparación para producción también requiere comprobaciones de permisos, pruebas de capacidades, comportamiento de limitación de velocidad, observabilidad, medición de costes y rollback.
¿Cuándo debería añadir un gateway de API?
Añade uno cuando gestionar claves de proveedor separadas, facturación, cuotas, reintentos y registros de uso empiece a ralentizar la entrega del producto, o cuando necesites pruebas repetibles entre modelos y enrutamiento de fallback. Mantén el acceso directo al proveedor cuando las funciones nativas del proveedor sean estratégicamente importantes y tu equipo pueda operar las integraciones adicionales.
Construye un acceso que pueda evolucionar
La mejor configuración de la API de OpenAI no es la que tiene menos campos de configuración. Es la que hace evidentes la propiedad, los permisos, los contratos de carga de trabajo, los límites y el rollback.
Empieza con acceso directo a OpenAI si eso es todo lo que necesita el producto. Coloca la clave, la URL base y el modelo detrás de una sola capa de configuración. Construye una matriz de pruebas de capacidades antes de añadir proveedores. Luego, si las operaciones con varios proveedores se convierten en el cuello de botella, mueve las cargas de trabajo compatibles a una capa de enrutamiento unificada sin perder las pruebas que las validaron.
Flatkey ofrece a los equipos multimodelo una única URL base compatible con OpenAI, una sola clave y controles centralizados de uso. Revisa los modelos disponibles y los precios actuales, y luego sigue el inicio de integración de Flatkey para ejecutar tu primera prueba controlada.
