OpenAI Python SDK: instalación, configuración e integración práctica

El SDK de OpenAI para Python (openai en PyPI) es el cliente oficial de Python para la API de OpenAI. Se encarga de la autenticación, el formato de las solicitudes, el análisis de las respuestas, el streaming y los reintentos. Esta guía cubre la instalación, la clase principal OpenAI, los chat completions, el streaming, las llamadas a funciones, el uso asíncrono, el equivalente del SDK de JavaScript, la integración con Azure OpenAI y la compatibilidad con Novita AI.

Instalación del paquete OpenAI para Python

Se requiere Python 3.10 o superior:

pip install openai

Si estás migrando desde la API heredada 0.x, reemplaza openai.ChatCompletion.create() por client.chat.completions.create().

Configura tu clave de API como una variable de entorno. No la pongas en el código fuente:

export OPENAI_API_KEY="sk-..."

La clase de cliente OpenAI

La clase OpenAI es el punto de entrada principal. Por defecto, lee la clave de API de la variable de entorno OPENAI_API_KEY, o puedes pasarla explícitamente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

El cliente gestiona el pool de conexiones, los reintentos y los timeouts. Debes crear una única instancia y reutilizarla en toda tu aplicación, no instanciarla por cada solicitud.

Opciones configurables en la inicialización:

Parámetro	Valor predeterminado	Descripción
api_key	variable de entorno OPENAI_API_KEY	Credencial de autenticación
base_url	https://api.openai.com/v1	Reemplazo para proxy o API compatible
timeout	600s	Timeout por solicitud
max_retries	2	Reintentos automáticos en errores de límite de tasa
http_client	None	Cliente httpx personalizado para proxy o configuración de certificados

Chat Completions: solicitud básica

Los chat completions son el caso de uso más común. La lista messages sigue el mismo formato que la API: una lista de diccionarios role/content que representan la conversación:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "What is the difference between a list and a tuple in Python?"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

La respuesta es un objeto ChatCompletion. Campos clave:

• response.choices[0].message.content — la respuesta de texto
• response.usage.prompt_tokens — tokens consumidos por la entrada
• response.usage.completion_tokens — tokens consumidos por la salida
• response.model — la versión del modelo que sirvió la solicitud

Para uso en producción, pasa max_tokens para evitar costos de generación descontrolados y temperature=0 o valores bajos cuando necesites salidas deterministas.

Respuestas en streaming

Para interfaces interactivas donde los usuarios ven los tokens a medida que llegan, usa stream=True:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Explain Python generators in plain language."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Usar el administrador de contexto (la declaración with) asegura que la conexión se cierre correctamente después de la iteración. El atributo .text_stream produce cadenas simples; .stream produce objetos de evento sin procesar si necesitas metadatos como estadísticas de uso por fragmento.

Si necesitas streaming sin administrador de contexto:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "List 5 Python best practices."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Llamada a funciones

La llamada a funciones permite que el modelo decida cuándo llamar a una función y devuelva un objeto JSON con los argumentos. Tu aplicación ejecuta la función y luego envía el resultado de vuelta para que el modelo lo incorpore a su respuesta:

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Returns current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'San Francisco'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    # Execute your actual function here
    result = {"city": args["city"], "temperature": "18°C", "condition": "cloudy"}

    messages.append(choice.message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

El modelo devuelve finish_reason="tool_calls" cuando quiere invocar una función. Ejecutas la función, agregas el resultado a la lista de mensajes y haces una segunda solicitud. Este bucle de dos pasos es el patrón estándar.

Uso asíncrono con AsyncOpenAI

Para FastAPI, servicios basados en asyncio o cualquier código que se beneficie de E/S no bloqueante, usa AsyncOpenAI:

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def get_response(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256,
    )
    return response.choices[0].message.content

async def main():
    result = await get_response("What is asyncio in Python?")
    print(result)

asyncio.run(main())

AsyncOpenAI es una contraparte asíncrona compatible; todos los métodos admiten await. Esto es preferible a usar asyncio.to_thread para envolver el cliente síncrono.

SDK de OpenAI para JavaScript

El SDK de OpenAI para JavaScript (openai en npm) refleja fielmente la interfaz de Python. Instálalo:

npm install openai

Solicitud básica de chat completion en Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain promises vs async/await in JavaScript." },
  ],
  max_tokens: 512,
});

console.log(response.choices[0].message.content);

Streaming en JavaScript:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Summarize the fetch API in 3 sentences." }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(text);
}

El SDK de JavaScript es compatible con Node.js 18+, Deno y entornos de navegador, pero exponer tu clave de API en el navegador es inseguro. Usa un proxy del lado del servidor en su lugar. La opción base_url para APIs compatibles funciona igual que en Python.

Integración de Azure OpenAI en Python

Si estás usando el servicio Azure OpenAI en lugar de la API directa de OpenAI, usa el cliente AzureOpenAI del mismo paquete:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

response = client.chat.completions.create(
    model="gpt-4o",  # Your deployment name in Azure
    messages=[
        {"role": "user", "content": "How do I use Azure OpenAI with Python?"},
    ],
)

print(response.choices[0].message.content)

Variables de entorno requeridas para Azure:

• AZURE_OPENAI_API_KEY: Tu clave de API del recurso Azure
• AZURE_OPENAI_ENDPOINT: La URL de tu endpoint, p. ej. https://your-resource.openai.azure.com/

El parámetro model en Azure OpenAI se refiere al nombre de tu implementación, no al nombre del modelo subyacente. Establece api_version para que coincida con la versión de la API de Azure que usa tu implementación (consulta la documentación de Azure OpenAI para conocer las versiones compatibles actuales).

Para autenticación mediante Microsoft Entra ID (anteriormente Azure AD) en lugar de una clave de API:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

Usa Novita AI con el mismo SDK

Novita AI expone un endpoint compatible con OpenAI en https://api.novita.ai/openai. Puedes usar el mismo SDK openai de Python o JavaScript y cambiar solo base_url y api_key:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v3.1",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Explain how Python's GIL affects multithreading."},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

Obtén una clave de API de Novita AI en novita.ai/settings/key-management. La misma clave funciona en todas las APIs de Novita AI, incluido el endpoint compatible con OpenAI.

JavaScript con Novita AI:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVITA_API_KEY,
  baseURL: "https://api.novita.ai/openai",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-coder-480b-a35b-instruct",
  messages: [{ role: "user", content: "Write a Python type annotation cheatsheet." }],
  max_tokens: 600,
});

console.log(response.choices[0].message.content);

Todo lo posterior (streaming, llamada a funciones, uso asíncrono, response_format, temperature y max_tokens) funciona igual.

Cuándo usar Novita Agent Sandbox

Usa el SDK de OpenAI para las llamadas al modelo y luego usa Novita Agent Sandbox cuando tu flujo de trabajo necesite ejecución de código, acciones de navegador u operaciones de archivos de forma aislada. Esto mantiene la capa del SDK enfocada en la inferencia, mientras que Sandbox se encarga de las partes riesgosas de un bucle de agente.

Modelos de código abierto a través de Novita AI

Cambiar base_url te da acceso a modelos de pesos abiertos en Novita AI sin cambiar el código de tu cliente. Eso es útil cuando quieres un modelo para programación, uso de herramientas o trabajo con contexto largo, pero aún quieres el mismo flujo de trabajo con el SDK.

El formato del ID de modelo en Novita AI es provider/model-name, y lo pasas directamente al parámetro model.

Un patrón de enrutamiento sencillo para equipos que quieren mezclar modelos abiertos y cerrados:

def get_client(use_novita: bool = False) -> OpenAI:
    if use_novita:
        return OpenAI(
            api_key=os.environ["NOVITA_API_KEY"],
            base_url="https://api.novita.ai/openai",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Use open-weight for cost-sensitive, high-volume coding tasks
coding_client = get_client(use_novita=True)

# Use OpenAI for tasks where the closed model is genuinely better
openai_client = get_client(use_novita=False)

Esto te permite hacer pruebas A/B de la calidad de las salidas, enrutar el trabajo a Novita AI cuando convenga y mantener una única vía de SDK entre proveedores.

Preguntas frecuentes

¿Cuál es el nombre del paquete OpenAI de Python?

El nombre del paquete en PyPI es openai. Instálalo con pip install openai.

¿Cómo se llama la clase de cliente OpenAI de Python?

La clase principal es OpenAI para uso síncrono y AsyncOpenAI para uso asíncrono. Ambas están en el módulo openai: from openai import OpenAI, AsyncOpenAI.

¿El SDK de OpenAI para Python admite streaming?

Sí. Usa client.chat.completions.stream() como administrador de contexto, o pasa stream=True a client.chat.completions.create() e itera sobre los fragmentos.

¿Cuál es el nombre del paquete del SDK de OpenAI para JavaScript?

El paquete npm es openai. Instálalo con npm install openai. Las firmas de clases y métodos son casi idénticas a las del SDK de Python.

¿Cómo uso Azure OpenAI con Python?

Usa la clase AzureOpenAI del paquete openai. Pasa azure_endpoint, api_key y api_version. El parámetro model se refiere al nombre de tu implementación de Azure, no al modelo subyacente.

¿Puedo usar el SDK de OpenAI para Python con otros proveedores?

Sí. Cualquier proveedor que implemente el formato de la API de Chat Completions de OpenAI se puede usar configurando base_url en el cliente. El endpoint de Novita AI en https://api.novita.ai/openai es un ejemplo; todo el conjunto de funciones del SDK (streaming, llamada a funciones, asíncrono) funciona sin cambios.

¿Cómo mantengo segura mi clave de API de OpenAI?

Guarda la clave en una variable de entorno (OPENAI_API_KEY) y léela con os.environ["OPENAI_API_KEY"]. Nunca la pongas en el código fuente, repositorios públicos, registros de compilación ni JavaScript del lado del cliente.

Artículos recomendados

• ¡Novita AI ahora es compatible con OpenAI Agents SDK! — Conecta los modelos de Novita AI al OpenAI Agents SDK para orquestación multiagente, salvaguardas y trazabilidad.
• Inicio rápido con Qwen3 Coder 30B A3B Instruct — ID de modelo, precios, ventana de contexto y ejemplos de API para este modelo de programación rentable en Novita AI.
• Vercel AI SDK: guía completa para desarrolladores de aplicaciones de IA — Usa el Vercel AI SDK con el endpoint compatible con OpenAI de Novita AI para streaming, llamadas a herramientas y bucles de agente en TypeScript.