Ir al contenido principal
Español— Elegir un idioma
Menú

Instalar el SDK de Python

Lección 4 de 22 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Instalar el SDK de Python
  2. Prerrequisitos e instalación
  3. Un cliente, todas las APIs
  4. Configurar el cliente para tu contexto
  5. Estructurar tu proyecto
  6. Tres fallos comunes
  7. Puntos clave

Instalar el SDK de Python

El SDK de Python openai es la biblioteca oficial para interactuar con la API. Esta lección te guía paso a paso en la instalación y configura una estructura de proyecto limpia que utilizarás durante el resto del curso.

Prerrequisitos e instalación

Necesitas Python 3.10 o superior, el mínimo requerido por el SDK openai (versión 3.42.1 a fecha de 2 de noviembre de 2026, según PyPI), un gestor de paquetes (pip o uv) y la clave de API que obtuviste en la lección anterior. Comienza confirmando tu intérprete, ya que las máquinas de desarrollo suelen alojar múltiples versiones:

python --version
# Python 3.12.4

La instalación requiere un único comando: pip install openai, o uv pip install openai si utilizas uv, que es significativamente más rápido. Sin embargo, haz el hábito de trabajar dentro de un entorno virtual. Esto evita el escenario común en el que, seis meses después, descubres que dos proyectos requieren versiones incompatibles de la misma biblioteca.

# Crear un entorno virtual
python -m venv .venv

# Activar (Linux/macOS)
source .venv/bin/activate

# Activar (Windows)
.venv\Scripts\activate

# Instalar el SDK
pip install openai

Dos compañeros aparecen en casi todos los proyectos y merecen instalarse junto al SDK. Pydantic ayuda a definir esquemas para la Salida Estructurada, que verás más adelante; python-dotenv carga el archivo .env en variables de entorno.

# Instalar con soporte para clases de datos de Pydantic
pip install openai pydantic

# Instalar con python-dotenv para variables de entorno
pip install openai python-dotenv

Finalmente, verifica que la importación funciona y toma nota de la versión instalada. Esta es la primera información que debes proporcionar si abres un ticket de soporte.

import openai
print(f"Versión del SDK de OpenAI: {openai.__version__}")
# Salida: Versión del SDK de OpenAI: 1.68.0 (o superior)

Un cliente, todas las APIs

El SDK gira en torno a un único objeto cliente que expone toda la plataforma mediante submódulos. No necesitas instanciar nada nuevo para cambiar de la generación de texto a incrustaciones o moderación.

from openai import OpenAI

client = OpenAI()

# API de Respuestas (texto, llamadas a funciones, salida estructurada)
client.responses.create(...)

# API de Completados de Chat (legado)
client.chat.completions.create(...)

# Incrustaciones (Embeddings)
client.embeddings.create(...)

# Imágenes
client.images.generate(...)

# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)

# Moderación
client.moderations.create(...)

Configurar el cliente para tu contexto

Los valores predeterminados del SDK funcionan para experimentación, pero se quedan cortos para aplicaciones web. El tiempo de espera predeterminado es de diez minutos: en una API HTTP que se espera responda en segundos, esto significa que una solicitud bloqueada ocupa un trabajador durante demasiado tiempo. Redúcelo y aumenta el número de reintentos automáticos, cuyo valor por defecto es dos.

from openai import OpenAI

client = OpenAI(
    timeout=60.0,  # 60 segundos (predeterminado: 10 minutos)
    max_retries=3,  # 3 intentos en caso de error (predeterminado: 2)
)

El parámetro base_url responde a otra necesidad: enrutar llamadas a través de un proxy corporativo que registra el tráfico saliente, o hacia un servicio que expone una API compatible.

# Útil para proxies corporativos o APIs compatibles
client = OpenAI(
    base_url="https://your-proxy.company.com/v1"
)

Finalmente, si tu aplicación depende de asyncio (FastAPI, aiohttp y similares), utiliza AsyncOpenAI. El cliente síncrono bloquearía el bucle de eventos durante la generación, anulando los beneficios del código asíncrono.

from openai import AsyncOpenAI

async_client = AsyncOpenAI()

# Uso con await
import asyncio

async def main():
    response = await async_client.responses.create(
        model="gpt-5.6-terra",
        input="¡Hola!"
    )
    print(response.output_text)

asyncio.run(main())
# Salida: ¡Hola! ¿En qué puedo ayudarte hoy?

Estructurar tu proyecto

Adopta una organización que aísle la configuración del cliente del resto de tu código desde el principio. Esto evita dispersar docenas de llamadas OpenAI() por todo tu proyecto, cada una con sus propios ajustes.

my-project/
├── .env                  # Clave de API (NUNCA hacer commit en git)
├── .gitignore            # Incluye .env
├── requirements.txt      # Dependencias
├── src/
│   ├── __init__.py
│   ├── client.py         # Configuración del cliente de OpenAI
│   └── main.py           # Punto de entrada
└── tests/
    └── test_api.py

El archivo src/client.py centraliza la fábrica del cliente: el día que cambies el tiempo de espera o añadas un proxy, solo necesitarás modificar una ubicación.

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

def get_client() -> OpenAI:
    """Devuelve un cliente de OpenAI configurado."""
    return OpenAI(
        max_retries=3,
        timeout=30.0
    )

Y requirements.txt fija las versiones mínimas esperadas:

openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0

Tres fallos comunes

Un ModuleNotFoundError en openai casi siempre indica un entorno virtual inactivo o uno diferente de donde instalaste el paquete. Localiza el intérprete que se está utilizando realmente con which python en Linux y macOS, o where python en Windows, y luego reinstala con pip install --upgrade openai. Un AuthenticationError apunta a la variable de entorno: imprime os.environ.get("OPENAI_API_KEY", "NOT DEFINED") para descartar problemas; el archivo .env no se carga si no se llamó a load_dotenv() antes de instanciar el cliente. Finalmente, un error relativo a un parámetro desconocido suele indicar un SDK demasiado antiguo para la función que estás utilizando: pip install --upgrade openai resuelve esto.

Puntos clave

  • Instala el SDK con pip install openai dentro de un entorno virtual
  • El cliente OpenAI() es el punto de entrada para todas las APIs
  • Utiliza AsyncOpenAI() para aplicaciones asíncronas
  • Configura el tiempo de espera y los reintentos según tus necesidades
  • Estructura tu proyecto con un archivo .env y un cliente centralizado