Integrar IA vía API: una guía práctica

Tienes una app. Quieres que hable con IA. Tal vez quieres chat completions, tal vez generación de imágenes, tal vez ambos. La buena noticia: si has usado la API de OpenAI, ya sabes cómo usar la nuestra. La mejor noticia: obtienes acceso a 367 modelos de 61 proveedores a través de un solo endpoint.

Sin SDK nuevo que aprender. Sin protocolo propietario. Solo cambia la URL base y tu clave API.

Paso 1: Obtén tu clave API

Regístrate en zubnet.com y navega a la configuración de tu espacio de trabajo. Tu clave API vive ahí. Empieza con un prefijo reconocible:

zub_live_a1b2c3d4e5f6...

Mantenla secreta. Trátala como una contraseña. Si se filtra, rótala inmediatamente desde la configuración de tu espacio de trabajo — la clave antigua deja de funcionar en el momento que generes una nueva.

Paso 2: Establece tu URL base

Cada petición va a:

https://api.zubnet.ai/v1

Eso es todo. El prefijo /v1 coincide con la convención de OpenAI, así que cualquier biblioteca, herramienta o framework que soporte OpenAI funcionará simplemente intercambiando la URL.

Paso 3: Haz tu primera petición

Usando curl

La prueba más simple posible — un chat completion con un mensaje:

curl https://api.zubnet.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zub_live_YOUR_KEY" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Recibirás una respuesta JSON con la respuesta del modelo en choices[0].message.content. Exactamente la misma forma que la respuesta de OpenAI.

Usando Python con el SDK de OpenAI

Instala el SDK si aún no lo has hecho:

pip install openai

Luego úsalo con nuestra URL base:

from openai import OpenAI

client = OpenAI(
    api_key="zub_live_YOUR_KEY",
    base_url="https://api.zubnet.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in three sentences."}
    ],
    max_tokens=500,
    temperature=0.7
)

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

Ese es un ejemplo completo y funcional. Cópialo, pégalo, reemplaza la clave API, ejecútalo.

El parámetro modelo

El campo model es donde se pone interesante. En vez de estar bloqueado a un proveedor, eliges de 367 modelos a través de 61 proveedores. Algunos ejemplos:

La lista completa está en nuestra página de modelos, filtrable por tipo (LLM, imagen, video, audio, 3D, código) y proveedor. El ID de modelo que ves ahí es exactamente lo que va en el campo model.

Generación de imágenes

Los modelos de imagen usan el mismo patrón de endpoint. Aquí está FLUX vía Python:

response = client.images.generate(
    model="flux-1.1-pro",
    prompt="A serene Japanese garden at dawn, soft morning light",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(image_url)

La respuesta incluye una URL a la imagen generada alojada en nuestro CDN. Descárgala, muéstrala, incrústala — la URL es válida por 24 horas.

Respuestas en streaming

Para modelos de chat, el streaming envía tokens según se generan en vez de esperar la respuesta completa. Esto es esencial para cualquier interfaz de chat de usuario — nadie quiere mirar una pantalla en blanco por 10 segundos.

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Write a short poem about code."}
    ],
    stream=True
)

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

Bajo el capó, esto usa Server-Sent Events (SSE). Cada chunk llega como una línea data: en la respuesta HTTP. El SDK de OpenAI maneja el parsing por ti, pero si usas HTTP crudo, verás líneas como:

data: {"choices":[{"delta":{"content":"Once"},"index":0}]}
data: {"choices":[{"delta":{"content":" upon"},"index":0}]}
data: {"choices":[{"delta":{"content":" a"},"index":0}]}
...
data: [DONE]

El flujo termina con data: [DONE]. Parsea cada línea, extrae delta.content, añade al buffer de salida. Ese es todo el protocolo.

Manejo de errores

La API usa códigos de estado HTTP estándar. Aquí están los que realmente encontrarás:

400 Bad Request — tu cuerpo de petición está mal formado. Revisa la estructura JSON, asegúrate que messages es un array, asegúrate que model es un ID de modelo válido.

401 Unauthorized — tu clave API está faltante, inválida o expirada. Revisa el header Authorization: Bearer.

403 Forbidden — tu cuenta no tiene acceso a este modelo o función. Revisa el nivel de suscripción de tu espacio de trabajo.

429 Too Many Requests — alcanzaste el límite de tasa. La respuesta incluye un header Retry-After diciéndote cuántos segundos esperar. Implementa backoff exponencial:

import time
from openai import RateLimitError

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="claude-sonnet-4-20250514",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except RateLimitError:
        wait = 2 ** attempt
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)

500 / 502 / 503 — problemas del lado del servidor. Son raros pero pasan. Reintenta con backoff. Si persisten, revisa nuestra página de estado Pulse.

Detalles de autenticación

Cada petición necesita un header Authorization:

Authorization: Bearer zub_live_YOUR_KEY

La clave está delimitada a tu espacio de trabajo. Todos los miembros del equipo en el mismo espacio de trabajo comparten la misma clave y pool de uso. Si necesitas seguimiento separado por miembro del equipo, crea espacios de trabajo separados.

Límites de tasa

Los límites de tasa dependen de tu nivel de plan. Los valores por defecto son generosos para la mayoría de casos de uso:

• Peticiones por minuto: varía por plan (60-600 RPM)
• Tokens por minuto: varía por modelo y plan
• Peticiones concurrentes: sin límite duro, pero 429s se dispararán si haces burst muy agresivamente

Los headers de límite de tasa están incluidos en cada respuesta:

x-ratelimit-limit-requests: 120
x-ratelimit-remaining-requests: 119
x-ratelimit-reset-requests: 0.5s

Lee estos headers. Construye tu cliente para respetarlos. Tus usuarios te agradecerán cuando sus peticiones no fallen aleatoriamente.

Poniéndolo todo junto

Aquí tienes una función Python lista para producción que maneja errores, reintentos y streaming:

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

client = OpenAI(
    api_key=os.environ["ZUBNET_API_KEY"],
    base_url="https://api.zubnet.ai/v1"
)

def ask(prompt, model="claude-sonnet-4-20250514", stream=False):
    for attempt in range(3):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
                stream=stream
            )
            if stream:
                return response  # iterate over chunks
            return response.choices[0].message.content
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            if attempt == 2:
                raise
            time.sleep(1)

# Usage
print(ask("Summarize the latest in quantum computing"))
print(ask("Same question, different model", model="gpt-4.1"))

Cambia modelos cambiando una cadena. Sin refactorización de código, sin nuevas dependencias, sin formato de respuesta diferente. Ese es el punto completo de la compatibilidad con OpenAI.

---

Todos los ejemplos de código en esta guía están probados y funcionando a marzo 2026. Cópialos, ejecútalos, construye sobre ellos. Para eso son.

¿Listo para empezar? Obtén tu clave API en zubnet.com