Migra de OpenAI a TokenLab en 5 minutos

La URL base es la parte sencilla de dejar un proveedor; las rutas de fallo son donde las migraciones salen mal. Para migrar de OpenAI a TokenLab, debes cambiar dos valores en tu cliente del SDK de OpenAI: base_url y api_key. El resto de esta guía cubre lo que debes confirmar en torno a ese cambio. Esto significa el ID del modelo que envías, su precio actual, streaming, llamadas a herramientas, manejo de errores, tiempos de espera y facturación. Los datos a continuación provienen de la documentación de TokenLab y de la API de modelos en vivo, cada uno con su fecha de observación.

Puntos clave

• El cambio principal son dos valores: la URL base de TokenLab https://api.tokenlab.sh/v1 y una clave API de TokenLab (comienzan con sk-).
• TokenLab documenta el soporte del SDK de OpenAI para Chat Completions y Responses. Los parámetros opcionales, las opciones de herramientas y los campos exclusivos de Responses siguen dependiendo del modelo seleccionado.
• Consulta el precio de tu modelo en la API en vivo antes de decidir nada. El 03-10-2026, gpt-5.5 cotizaba a $1.50 de entrada y $9.00 de salida por cada 1 millón de tokens.
• Ejecuta la lista de verificación al final antes de mover el tráfico de producción. La mayoría de las sorpresas residen en el manejo de errores, tiempos de espera y facturación, no en el camino feliz (happy path).

El cambio de dos valores para migrar de OpenAI a TokenLab

Comienza con la clave. Según el Quickstart (observado el 03-10-2026), creas una cuenta, generas una clave API y guardas el valor completo inmediatamente. Solo se muestra una vez, y el prefijo en la lista de claves no puede autenticar solicitudes. Verifica tu saldo antes de la primera llamada, ya que las solicitudes se facturan al precio actual del modelo seleccionado.

Luego cambia el cliente. La guía de migración (observada el 03-10-2026) describe la receta como: establecer base_url / baseURL en https://api.tokenlab.sh/v1, reemplazar la clave y elegir un ID de modelo desde GET /v1/models.

Por ejemplo, imagina un servicio que tiene la cadena gpt-5.5 en su configuración. Después del cambio de dos valores, esa misma cadena es una solicitud válida, pero aun así confirmaríamos el ID primero. GET /v1/models y GET /v1/models/{model} son endpoints de descubrimiento públicos y funcionan sin necesidad de una clave.

Python

import os
from openai import OpenAI

# Antes: client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

// Antes: new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
  timeout: 30_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hello"}]}'

La configuración de tiempo de espera (timeout) y reintentos en los dos primeros ejemplos refleja los ejemplos del Quickstart (observado el 03-10-2026), que utilizan un tiempo de espera de 30 segundos y cero reintentos en el SDK. Mantenemos los reintentos en cero durante las pruebas para que una solicitud fallida sea visible en lugar de ser reintentada silenciosamente.

Pasa la URL base explícitamente en la configuración del cliente. La guía de SDK (observada el 03-10-2026) recomienda esto en lugar de depender de alias de variables de entorno más antiguos. Mantén la clave en el servidor y en un gestor de secretos, nunca en el código del lado del cliente.

Elige el ID del modelo y consulta su precio

Una migración no debe asumir un ID de modelo o un precio. Ambos residen en la API de modelos. Leímos https://api.tokenlab.sh/v1/models/gpt-5.5 y https://api.tokenlab.sh/v1/models/laguna-s-2.1 el 03-10-2026. Los precios de ambos se actualizaron por última vez el 2026-10-02T16:53:30.068Z.

Campo	gpt-5.5	laguna-s-2.1
Etapa del ciclo de vida	active	active
Tokens máx. entrada / salida	1,000,000 / 128,000	1,048,576 / 131,072
Formatos de solicitud aceptados	openai_chat_completions, openai_responses	openai_chat_completions
Capacidades listadas	coding, json-mode, prompt-cache, reasoning, tool-use, vision	tool-use
Entrada, USD por 1M tokens	1.5	0.1
Salida, USD por 1M tokens	9	0.2
Lectura de caché, USD por 1M tokens	0.15	0.01

Fuentes: gpt-5.5 y laguna-s-2.1, ambos observados el 03-10-2026.

Para convertir esas tasas en un número, aquí hay una estimación con el cálculo mostrado. Tomemos un trabajo con 1M de tokens de entrada y 100k de tokens de salida, sin aciertos de caché.

• gpt-5.5: 1 × $1.50 + 0.1 × $9.00 = $1.50 + $0.90 = $2.40.
• laguna-s-2.1: 1 × $0.10 + 0.1 × $0.20 = $0.10 + $0.02 = $0.12.

Estas son estimaciones basadas en las tasas por token listadas. Tu cargo final es el registro de Uso (Usage). La tokenización difiere según el modelo, por lo que el mismo texto produce diferentes conteos de tokens en diferentes modelos.

No afirmamos un ahorro aquí. Para comparar con lo que pagas hoy, coloca las tasas de TokenLab junto a tu propia factura de OpenAI, o la página de precios de OpenAI, el día que cambies. Los precios cambian, y la guía de facturación (observada el 03-10-2026) dice que no se debe codificar de forma rígida una tabla de precios copiada. Indica usar GET /v1/models/:model/pricing para obtener los valores actuales.

Otros IDs de modelos siguen el mismo patrón. Los ejemplos de la documentación usan gpt-5.6-terra y gpt-5.6-luna para Chat Completions, y claude-sonnet-5 y gemini-3.5-flash en sus propias rutas. Lee los formatos aceptados de cada modelo antes de dirigir tráfico hacia él. Para comparaciones más amplias, consulta el directorio de modelos, la comparación OpenRouter vs TokenLab y los rankings de modelos. Los equipos de imagen y video pueden comenzar con la mejor API de modelos de IA de imagen 2026 y la mejor API de modelos de IA de video 2026. Para tareas de código, consulta los mejores modelos de IA para programación.

Qué comprobar a continuación al migrar de OpenAI a TokenLab

TokenLab documenta el SDK de OpenAI como funcional con Chat Completions y Responses. Eso es compatibilidad con el formato de solicitud y respuesta, no una promesa de que cada modelo se comporte igual. La guía de formatos de API (observada el 03-10-2026) dice que los parámetros opcionales dependen del modelo. También dice que un modelo no necesariamente acepta los cuatro formatos de API, y tokenlab.accepted_request_formats muestra cuáles acepta. Trata cada área a continuación como algo que debes probar con tu tráfico real.

Streaming

stream: true envía deltas de mensajes parciales como eventos enviados por el servidor (SSE). Establece stream_options con include_usage: true para recibir el uso de tokens en fragmentos de flujo, tal como lo documenta la referencia de Create Chat Completion (observada el 03-10-2026).

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

Dos comportamientos a planificar. Si un flujo se interrumpe después de que llegó la salida, no lo trates como una respuesta completa. La guía de manejo de errores (observada el 03-10-2026) advierte que repetirlo puede producir una salida diferente o un segundo cargo. Y el streaming puede terminar antes que la facturación, por lo que el ID de facturación puede estar ausente.

Llamadas a herramientas (Tool calls)

La referencia de Chat Completions enumera tools, tool_choice y parallel_tool_calls. Dice que las llamadas paralelas funcionan "cuando son compatibles con el modelo seleccionado". La llamada a funciones está documentada como "compatible con el modelo seleccionado", así que verifica la lista de capacidades. En la tabla anterior, tanto gpt-5.5 como laguna-s-2.1 listan tool-use, pero solo gpt-5.5 lista json-mode y vision. Envía tus esquemas de herramientas reales, no un ejemplo de juguete, y verifica que los argumentos devueltos se analicen correctamente.

Si planeas llamar a modelos Claude, ten en cuenta la regla de la guía de migración. Las llamadas a herramientas de Claude, los bloques de pensamiento y los campos de mensajes de Anthropic pertenecen a /v1/messages, y Chat Completions no los garantiza.

Formas de error

Chat Completions y Responses devuelven un objeto error al estilo de OpenAI. Según la guía de manejo de errores, solo message y type están siempre presentes. Campos como code, param, retryable y retry_after aparecen cuando es relevante. Ramifica según el estado HTTP y el code, no según el texto del mensaje, y haz que tu analizador tolere campos faltantes. Anthropic Messages y Gemini mantienen sus propios formatos de error, por lo que un solo analizador no cubrirá todas las rutas.

Estado	Código	Qué significa
401	invalid_api_key	La clave falta, es inválida, inactiva o fue revocada
401	expired_api_key	La clave ha expirado
402	insufficient_balance	El saldo de la cuenta no puede cubrir la solicitud
402	quota_exceeded	Se alcanzó el límite de uso propio de la clave
403	model_not_allowed	Esta clave no puede usar el modelo solicitado
429	rate_limit_exceeded	Demasiadas solicitudes; espera por Retry-After

Fuentes: Autenticación y manejo de errores, observados el 03-10-2026.

Esta tabla corrige una suposición común. Un saldo vacío es un 402, no un 401. Si tu código actual trata cada 4xx como una clave incorrecta, actualízalo.

Tiempos de espera y reintentos

La guía de migración dice que el código existente de reintento, tiempo de espera y streaming generalmente puede permanecer igual. Revísalo contra las reglas de reintento documentadas.

• No repitas respuestas 400, 401, 402, 403, 404 o 413 sin cambios.
• Reintenta 429 después del retraso proporcionado por el servidor.
• Reintenta 500–504 solo cuando retryable sea true, y respeta retry_after.
• Un 503 all_channels_failed puede regresar con retryable: false. En ese caso, la operación no tiene suministro en el nivel de entrega seleccionado, por lo que repetirla no ayudará.

Guarda el ID de solicitud (Request ID) de los encabezados de respuesta junto con el modelo y tu propio ID de trabajo. Es lo que necesitas para una investigación.

Facturación

Un saldo funciona en todos los modelos, sin suscripción ni gasto mínimo, según la guía de facturación. Cada solicitud completada se cobra una vez, por la opción de entrega que la produjo. Las opciones son TokenLab Verified, Official y Auto, y Auto intenta primero Verified, luego Official. Establece un límite de gasto en cada clave API si deseas un tope estricto. Cuando se alcanza el límite, las solicitudes con esa clave devuelven 402.

Las respuestas compatibles con OpenAI que no son de streaming incluyen billing_transaction_id cuando la facturación termina antes de que se envíe la respuesta. También puede aparecer en el encabezado X-Billing-Transaction-ID. Guárdalo y reconcilia con la página de Uso (Usage) en lugar de hacer tus propios cálculos de tokens.

Lista de verificación de verificación después de migrar de OpenAI a TokenLab

Ejecuta esto en orden contra una clave de staging antes de mover el tráfico de producción. Cada fila sigue un comportamiento documentado anteriormente.

Paso	Qué ejecutar	Qué deberías ver
1. Descubrimiento de modelo	GET /v1/models/gpt-5.5 (no se necesita clave)	Ciclo de vida active y los formatos aceptados que planeas usar
2. Solicitud autenticada	El ejemplo de Python o cURL anterior	Una respuesta no vacía; la solicitud aparece en la vista de Solicitudes con modelo, estado y uso
3. Campos de uso	Leer usage en una respuesta sin streaming	prompt_tokens, completion_tokens, total_tokens
4. Streaming	stream: true con include_usage: true	Fragmentos SSE, luego uso; un flujo interrumpido se maneja como incompleto
5. Llamadas a herramientas	Tus tools y tool_choice reales	Los argumentos se analizan y coinciden con tu esquema
6. Visión o modo JSON	Solo si el modelo lista vision o json-mode	Salida esperada; omite la prueba si la capacidad no está listada
7. Clave incorrecta	Solicitud con una clave eliminada o incorrecta	401 invalid_api_key
8. Sin saldo o límite de clave	Usa una clave con un límite bajo o un espacio de trabajo vacío	402 insufficient_balance o quota_exceeded
9. Restricción de modelo	Restringe la lista de modelos de una clave, luego solicita otro	403 model_not_allowed
10. Tiempo de espera y reintento	Forzar un tiempo de espera en staging	Tu código reintenta solo según retryable y retry_after
11. Facturación	Compara billing_transaction_id y Uso con tu estimación	El cargo coincide con el precio actual del modelo y los tokens registrados

Después de que la tabla pase, cambia tu configuración de producción y despliega. Mantén la antigua clave de OpenAI activa hasta que el Uso confirme que la nueva ruta es estable.

Preguntas frecuentes

¿Necesito cambiar los nombres de mis modelos cuando cambio desde OpenAI?

No necesariamente, pero confirma cada uno. Los IDs de modelos de TokenLab son cadenas exactas, así que verifícalos con GET /v1/models o GET /v1/models/{model}. El 03-10-2026, la API en vivo listaba gpt-5.5 como activo. Si una solicitud devuelve model_not_found, el ID es desconocido o no está disponible. Lee la lista de modelos y usa un ID actual.

¿El streaming y las llamadas a herramientas se comportarán exactamente como la API de OpenAI?

TokenLab documenta el streaming a través de SSE y la llamada a funciones a través del formato de solicitud compatible con OpenAI. Los documentos también dicen que las opciones compatibles dependen del modelo seleccionado. Por lo tanto, tratamos el resultado como compatible, no idéntico. Prueba el streaming, tools, tool_choice y cualquier response_format que uses con el modelo específico que planeas ejecutar.

¿Qué código de estado obtengo cuando se agota mi saldo?

Obtienes HTTP 402 con el código insufficient_balance. Una clave que alcanzó su propio límite de gasto también devuelve 402, con quota_exceeded. Una clave faltante, inválida o revocada devuelve 401. No reintentes ninguno de estos sin cambios. Recarga el saldo, aumenta el límite de la clave o reemplaza la clave.

¿Puedo llamar a modelos Claude o Gemini desde el mismo cliente de OpenAI?

El catálogo de modelos lista claude-sonnet-5 y gemini-3.5-flash con openai_chat_completions entre sus formatos de solicitud. Por lo tanto, el chat básico puede pasar por el mismo cliente. Los campos específicos de Claude, como los bloques de pensamiento y el uso de herramientas de Claude, pertenecen a /v1/messages. Los campos nativos de Gemini permanecen en la ruta /v1beta. Mantén un formato de API por conversación.

Comienza a construir en TokenLab

Crea una clave en TokenLab, establece la URL base en https://api.tokenlab.sh/v1 y ejecuta la solicitud del Quickstart antes de tocar la producción.