Integrar OpenAI API requiere solo cuatro cosas: una cuenta con la que puedas iniciar sesión, una API Key utilizable, un proyecto con facturación habilitada y una Base URL correcta junto con una primera llamada exitosa. Suena simple, pero lo que suele detener a los equipos nuevos no es el código, sino el sistema de cuentas, los métodos de pago y el armado de la dirección.

Este artículo recorre el orden real de operación: cuenta y proyecto, creación de la Key, recarga, instalación del SDK, primera llamada con Responses API, revisión del uso, diagnóstico de errores 401 y 429, y por último cómo cambiar la Base URL a una pasarela compatible con OpenAI. Los ejemplos se centran en Responses API; las herramientas antiguas que solo admiten Chat Completions pueden sustituir la interfaz con la misma lógica.

Nota: OpenAI, ChatGPT y GPT son marcas de OpenAI. Este artículo toma como ejemplo el comportamiento público de las interfaces en octubre de 2026; los nombres de modelo, las cuotas y los precios se rigen por los precios de modelos y la documentación oficial.

1. Qué son la cuenta, la organización y el proyecto

La plataforma de OpenAI tiene al menos tres capas, y mezclarlas es la fuente más común de errores:

  • Cuenta: la credencial de acceso, define quién puede entrar a la consola.
  • Organización: la unidad a la que se atribuyen la facturación y el uso; la colaboración en equipo suele gestionarse por organización.
  • Proyecto: la unidad de aislamiento de Keys, uso y permisos; conviene separar por entorno o por línea de negocio.

Un error frecuente es confundir la suscripción a ChatGPT con el saldo de API. Son cosas distintas: la suscripción da acceso al producto de chat y la API se factura aparte según el consumo real. Antes de integrar, el equipo debe definir quién administra la cuenta, quién paga y quién tiene permisos de administrador, para que más adelante no se pierda la titularidad de las Keys cuando cambien las personas.

2. Orden para crear una API Key

Sigue estos pasos sin saltarte ninguno:

  1. Inicia sesión en la consola de API con una cuenta de administrador y confirma que estás en la organización correcta.
  2. Crea o selecciona un proyecto dentro de la organización y sepáralo por "desarrollo / pruebas / producción".
  3. Entra a la página API Keys del proyecto y crea una clave nueva.
  4. Ponle un nombre que indique su uso, por ejemplo "producción-robot-de-soporte".
  5. Copia la Key completa de inmediato y guárdala en un gestor de contraseñas o en el gestor de secretos de tu plataforma de despliegue.
  6. Configura los permisos, el presupuesto o el límite de cuota del proyecto según necesites y guarda.

La Key completa suele mostrarse una sola vez, al crearla. Es normal que la página solo conserve los primeros y últimos caracteres; no cuentes con poder copiarla de nuevo. Si se pierde, crea una Key nueva y desactiva la anterior en lugar de intentar recuperarla.

3. Recarga, facturación y cuota

Que la API funcione con prepago o pospago depende del tipo de cuenta y de la región, y se rige por lo que muestre la consola. Antes de habilitarla, revisa tres puntos:

  1. Si el método de pago admite tu tarjeta o canal.
  2. Cómo se obtienen el ciclo de facturación y las facturas.
  3. Si puedes configurar alertas de presupuesto y límites máximos por proyecto.

Los pagos rechazados son un problema habitual en la etapa de integración. Si la tarjeta es rechazada, revisa primero la dirección de facturación, el nombre del titular y el método de verificación, y luego contacta al banco emisor; no envíes el pago repetidamente en poco tiempo, porque algunos sistemas antifraude bloquean la tarjeta por eso. Los equipos que usan una pasarela suelen poder recargar en yuanes; las tarifas y reglas de acreditación se rigen por la página de precios, y los precios cambian, así que confirma lo que muestra la página antes de ordenar.

4. Instalar el SDK y enviar la primera petición con curl

Instala primero el SDK oficial de Python:

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-tu-clave"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="nombre-de-modelo-copiado-de-la-pagina-de-precios"

Llama a Responses API con curl para confirmar que la dirección, la Key y la red funcionan:

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "Explica en una frase qué es una pasarela de API."
  }'

No escribas el nombre del modelo de memoria: copia el nombre disponible actualmente desde la página de precios o la documentación oficial y guárdalo en la variable de entorno OPENAI_MODEL. Si recibes un 200 con contenido en el cuerpo, el enlace ya funciona; si recibes 401, revisa primero la Key; si recibes 404, revisa la Base URL y el nombre del modelo.

5. Primera llamada en Python

El siguiente ejemplo envía una petición mínima a Responses API e imprime el texto resultante:

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"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="Describe en tres frases los límites de tus capacidades.",
)

print(resp.output_text)

Si tu framework solo admite Chat Completions, cambia la llamada por client.chat.completions.create(...) y coloca los mensajes en messages. Las dos interfaces usan rutas distintas, y mezclarlas es la causa más frecuente de un 404.

6. Entender el uso y la facturación

La página Usage de la consola suele mostrar el consumo por proyecto, modelo y periodo, y separa entrada y salida. Al principio conviene revisarla una vez al día y confirmar:

  • Qué proyecto está consumiendo.
  • Cuánto corresponde a entrada y cuánto a salida.
  • Si hay reintentos fallidos anómalos.
  • Si las alertas de presupuesto están activas.

Guarda el ID de petición que devuelve cada llamada en los registros. Ante una disputa de facturación o una falla, ese ID es el primer material con el que el proveedor puede localizar el problema. El equipo también debería registrar en la aplicación la relación entre usuario, módulo funcional e ID de petición; de lo contrario, la factura solo muestra el total y no permite atribuir costos.

7. Cómo diagnosticar 401 y 429

Un 401 significa que la identidad no fue reconocida. Revisa en orden: si la cabecera incluye Bearer; si la Key tiene espacios o saltos de línea de más; si la Key fue eliminada o el proyecto está deshabilitado; si enviaste una Key de pasarela a la dirección oficial. Antes de cambiar la Key, confirma a dónde se envía realmente la petición; de lo contrario podrías perder tiempo sin motivo.

Un 429 tiene dos significados: límite de velocidad y saldo insuficiente. Mira el código de error y las cabeceras de la respuesta en lugar de bajar la velocidad sin más. insufficient_quota suele indicar saldo o cuota, y requiere recargar o ajustar el límite del proyecto; solo los errores de velocidad admiten retroceso exponencial. Reintentar tiene sentido únicamente para 429, 5xx y errores de red; repetir un 400, 401, 403 o 404 solo consume cuota. Encontrarás el orden completo de diagnóstico en Errores de OpenAI API.

8. Conexión directa oficial o pasarela compatible

Dimensión Conexión directa oficial Pasarela compatible con OpenAI
Dirección de acceso https://api.openai.com/v1 La Base URL que da la pasarela, normalmente terminada en /v1
Cuenta y pago Cuenta oficial, con los medios de pago que admite Cuenta en el sitio, con recarga en yuanes y facturas
Red Depende de la red local y del enlace internacional Suele ofrecer una entrada accesible desde China
Alcance de modelos Modelos propios de OpenAI Puede ofrecer modelos de varios proveedores; rige la página de precios
Facturación Factura oficial Saldo y registro de uso en el sitio
Gestión de fallas Canales de soporte oficiales La pasarela diagnostica el upstream; el usuario conserva el ID de petición
Casos adecuados Solo OpenAI, con un canal de pago conforme Equipos en China, varios modelos, factura unificada

Al elegir, no mires solo el precio unitario. La fluidez del pago, quién resuelve las fallas y la posibilidad de cambiar de modelo en cualquier momento afectan el costo a largo plazo. Los precios cambian; rige siempre la página de precios.

9. Cambiar a una pasarela compatible: solo la Base URL

El costo de migración suele ser menor de lo que parece, porque una pasarela compatible conserva el mismo formato de petición. El orden de operación:

  1. Regístrate en la pasarela y crea una Key desde la página de registro.
  2. Cambia OPENAI_BASE_URL por la dirección de la pasarela y conserva /v1.
  3. Sustituye la Key por la de la pasarela; no mezcles las dos.
  4. Copia el nombre del modelo desde la página de precios de la pasarela; no reutilices el nombre oficial a la espera de que funcione.
  5. Prueba primero /v1/models y una petición mínima, y después mueve el tráfico de producción.
  6. Conserva la conexión oficial o una línea de respaldo como plan de degradación.

"Compatible con OpenAI" significa que los formatos de petición y respuesta son compatibles, no que todas las capacidades extendidas sean idénticas. La compatibilidad de archivos, lotes, llamadas a herramientas y otras interfaces avanzadas debe verificarse una por una en la documentación de la pasarela; no des por hecho que todo está disponible. Puedes consultar los detalles del alcance de compatibilidad en API compatible con OpenAI.

10. Seguridad de las Keys y revisión antes de salir a producción

Una Key filtrada genera costos directos. Requisitos mínimos:

  • Guarda la Key solo en variables de entorno del servidor o en un servicio de gestión de secretos; no la escribas en el código del frontend ni la subas a Git.
  • Separa las Keys por entorno; pruebas y producción no deben compartirla.
  • Anota el responsable y el uso de cada Key, y desactívala cuando la persona salga o cambie de proyecto.
  • No imprimas la Key completa en los registros; conserva solo los últimos cuatro caracteres.
  • Rota las Keys periódicamente y revoca de inmediato cualquier llamada anómala.

Confirma cada punto antes de salir a producción:

  • [ ] La titularidad de cuenta, organización y proyecto está clara.
  • [ ] El método de pago funciona y las alertas de presupuesto están configuradas.
  • [ ] La Key está en variables de entorno o en un gestor de secretos.
  • [ ] La Base URL tiene un solo /v1.
  • [ ] La petición mínima devuelve 200 con contenido normal.
  • [ ] El retroceso para 429 y los reintentos para 5xx están configurados.
  • [ ] El registro de uso incluye ID de petición, modelo y latencia.
  • [ ] La línea de respaldo y el proceso para desactivar Keys ya se practicaron.

11. Preguntas frecuentes

¿Una API Key y la suscripción a ChatGPT son lo mismo?

No. La suscripción y la API se facturan por separado, y la API Key solo se crea y gestiona en la plataforma de API. Al reembolsar gastos, el equipo debe distinguir ambos conceptos.

¿Por qué no veo la Key completa después de crearla?

La clave completa suele mostrarse una sola vez al crearla, y la plataforma conserva solo algunos caracteres para identificarla. Si se pierde, crea una nueva y desactiva la anterior.

¿Hasta dónde se escribe la Base URL?

Hasta el dominio más /v1, sin /chat/completions ni /responses. La ruta la compone el SDK o la petición; agregar un segmento de más produce un 404.

¿Puedo usar una Key en varios proyectos?

Técnicamente sí, pero no es recomendable desde el punto de vista de gestión. Separar Keys por proyecto o entorno permite controlar permisos, atribuir uso y reducir el impacto si hay una filtración.

¿Un equipo en China necesita obligatoriamente una pasarela?

No necesariamente. Depende del canal de pago, la calidad de la red, los requisitos de cumplimiento y la necesidad de varios modelos. Los equipos que solo usan OpenAI y ya tienen pagos y red estables pueden conectarse directo; quienes necesitan liquidación en yuanes y una entrada unificada pueden evaluar la migración con ayuda de API compatible con OpenAI.

Siguiente paso

Primero haz funcionar la petición mínima y después conecta el negocio. Si necesitas recarga en yuanes y una entrada unificada para varios modelos, puedes empezar por registrarte en ZSQH AI Gateway; los modelos y precios se rigen por los precios de modelos.

Lecturas relacionadas: