Tutorial de la API de OpenAI en Python

Este tutorial cubre el uso de la API de OpenAI con Python desde la instalación hasta casos de uso avanzados. Todos los ejemplos funcionan con APIMaster.ai: solo cambia api_key y base_url.

Instalación

pip install openai

Requiere Python 3.8+. El paquete openai es el SDK oficial de OpenAI para Python (versión 1.x).

Configuración Inicial

from openai import OpenAI

client = OpenAI(
    api_key="TU_CLAVE_APIMASTER",
    base_url="https://apimaster.ai/v1",
)

O usa variables de entorno (recomendado):

export OPENAI_API_KEY="TU_CLAVE_APIMASTER"
export OPENAI_BASE_URL="https://apimaster.ai/v1"

from openai import OpenAI
client = OpenAI()  # lee las variables de entorno automáticamente

Completions de Chat Básicos

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "Eres un experto en Python."},
        {"role": "user", "content": "¿Qué es un generador en Python?"},
    ],
)

print(response.choices[0].message.content)
print(f"Tokens usados: {response.usage.total_tokens}")

Respuestas en Streaming

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Escribe una búsqueda binaria en Python."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

Conversaciones de Múltiples Turnos

messages = [
    {"role": "system", "content": "Eres un asistente de codificación útil."}
]

def enviar(texto_usuario):
    messages.append({"role": "user", "content": texto_usuario})
    resp = client.chat.completions.create(model="gpt-5.4", messages=messages)
    respuesta = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": respuesta})
    return respuesta

print(enviar("Explica las comprensiones de listas."))
print(enviar("Dame un ejemplo más difícil."))

Salida Estructurada (Modo JSON)

Fuerza al modelo a devolver JSON válido:

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {
            "role": "user",
            "content": "Extrae el nombre, correo electrónico y empresa de: 'Contacto Jane Smith (jane@acme.com) en Acme Corp.'",
        }
    ],
    response_format={"type": "json_object"},
)

data = json.loads(response.choices[0].message.content)
print(data)  # {"name": "Jane Smith", "email": "jane@acme.com", "company": "Acme Corp"}

Llamadas a Funciones (Uso de Herramientas)

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "obtener_precio_accion",
            "description": "Obtiene el precio actual de una acción para un símbolo",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {"type": "string", "description": "Símbolo bursátil, p. ej. AAPL"},
                },
                "required": ["ticker"],
            },
        },
    }
]

messages = [{"role": "user", "content": "¿Cuál es el precio actual de las acciones de Apple?"}]

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

# Procesar llamada a la herramienta
if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"Llamando a {tool_call.function.name} con {args}")
    
    # Simular resultado de la función
    result = {"ticker": args["ticker"], "price": 189.50}
    
    # Enviar resultado de vuelta
    messages.append(response.choices[0].message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })
    
    final = client.chat.completions.create(model="gpt-5.4", messages=messages)
    print(final.choices[0].message.content)

Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Tutorial de la API de OpenAI en Python", "Conceptos básicos de machine learning"],
)

embeddings = [item.embedding for item in response.data]
print(f"Dimensiones del embedding: {len(embeddings[0])}")

Uso Asíncrono

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="TU_CLAVE_APIMASTER",
    base_url="https://apimaster.ai/v1",
)

async def generar(prompt: str) -> str:
    resp = await client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content

async def main():
    # Ejecutar 5 solicitudes concurrentemente
    prompts = [f"Explica el concepto #{i}" for i in range(5)]
    results = await asyncio.gather(*[generar(p) for p in prompts])
    for r in results:
        print(r[:100])

asyncio.run(main())

Manejo de Errores

from openai import OpenAI, AuthenticationError, RateLimitError, APIError
import time

def llamada_segura(client, **kwargs):
    for intento in range(3):
        try:
            return client.chat.completions.create(**kwargs)
        except AuthenticationError:
            raise  # No reintentar errores de autenticación
        except RateLimitError:
            time.sleep(2 ** intento)
        except APIError as e:
            if e.status_code >= 500:
                time.sleep(1)
            else:
                raise
    raise RuntimeError("Se superó el máximo de reintentos")

Guía de Selección de Modelos

Tarea	Modelo	Por qué
Resumen, clasificación	gpt-4o-mini	Bajo costo
Codificación general, escritura	gpt-5.4	Mejor equilibrio
Razonamiento complejo	gpt-5.5 o o3	Alta capacidad
Procesamiento por lotes	gpt-4o-mini o gpt-5.4	Elige según calidad y presupuesto

Preguntas Frecuentes

¿Cómo instalo la biblioteca OpenAI de Python? Ejecuta pip install openai. Para acceso a APIMaster, no se necesita paquete adicional: solo configura base_url y api_key al inicializar el cliente.

¿Qué versión de Python se requiere para la biblioteca OpenAI? Python 3.8 o posterior. El cliente asíncrono requiere Python 3.10+ para una mejor compatibilidad.

¿Cómo manejo los límites de velocidad de la API de OpenAI en Python? Usa retroceso exponencial: captura RateLimitError y reintenta con demoras crecientes. La biblioteca tenacity simplifica esto. El enrutamiento de APIMaster proporciona estabilidad adicional.

¿Puedo usar la biblioteca de OpenAI con modelos Claude? Sí, a través de APIMaster. Configura base_url="https://apimaster.ai/v1" y usa IDs de modelo como claude-sonnet-4-6. El formato de respuesta es idéntico al de las respuestas GPT.

¿Cómo uso llamadas asíncronas de OpenAI en Python? Usa AsyncOpenAI en lugar de OpenAI, y await las llamadas a la API. Consulta el ejemplo asíncrono en la guía anterior.

Obtén acceso a la API de OpenAI a través de APIMaster →