Consigue tu llave: qué es una API, un modelo y un proveedor

OpenCode es la herramienta, pero no trae un modelo dentro: se conecta a uno que corre en la nube. Para conectarlo necesitas una llave (API key) de un proveedor de modelos. En esta lección primero entiendes qué son esas piezas y por qué funcionan así; después eliges proveedor, creas tu cuenta y guardas tu llave. La parte práctica son unos 5 minutos.

Una advertencia honesta: estos pasos son sobre páginas web reales, y las páginas cambian. Esta guía es de septiembre de 2026. Si un botón se llama distinto, la lógica es la misma.

Cuatro conceptos, en palabras simples

Qué es un modelo

Un modelo de lenguaje (o simplemente modelo) es la IA propiamente dicha: un programa enorme, entrenado con muchísimo texto, que recibe texto y produce texto. Le das una pregunta o un encargo, y contesta. Es el "cerebro" que OpenCode consulta cada vez que tiene que decidir qué hacer.

Los modelos buenos son tan grandes que no caben cómodos en una laptop normal. Por eso corren en computadoras potentes de otras empresas, en la nube.

Qué es un proveedor

Un proveedor de modelos es la empresa que tiene esos modelos corriendo en sus servidores y te deja usarlos a través de internet. Algunos proveedores fabrican sus propios modelos; otros, como OpenRouter, son un intermediario que te da acceso a modelos de muchas empresas desde una sola cuenta.

Qué es una API

Una API (interfaz de programación de aplicaciones) es la forma en que un programa le pide algo a otro programa. Piensa en un restaurante:

• Tú (OpenCode) estás en la mesa.
• La cocina (el modelo) prepara la comida, pero no entras a la cocina.
• El mesero (la API) toma tu pedido con un formato claro, lo lleva a la cocina y te trae el plato.

No necesitas saber cómo funciona la cocina. Solo necesitas saber pedir de la forma que el mesero entiende. OpenCode ya sabe hablar con las API de muchos proveedores; tú solo le das la llave.

Qué es una llave (API key) y por qué es secreta

Una API key es una cadena de texto secreta que le dice al proveedor quién está pidiendo. Siguiendo con el restaurante, es como tu número de cuenta de cliente: el mesero la anota en cada pedido, y todo lo que se pida con ella se carga a tu nombre.

Por eso es secreta. Quien tenga tu llave puede hacer pedidos como si fueras tú: gastar tu límite gratis o, si algún día pones una tarjeta, gastar tu dinero. No la prestas, no la pegas en un chat y no la muestras en pantalla.

Cómo viaja una petición

Cada vez que OpenCode necesita que el modelo piense, arma una petición (en inglés, request): un paquete con tu encargo, el contenido que haya leído de tus archivos y tu llave. Esto es lo que pasa:

  TU LAPTOP                               LA NUBE
+--------------+                  +-----------------------------------+
|              |  1. peticion     |  Proveedor                        |
|   OpenCode   |  (encargo +      |  (OpenRouter, Zen o Groq)         |
|              |   archivos +     |                                   |
|              |   tu llave)      |  2. Revisa la llave:              |
|              | ---------------> |     es valida? le queda limite? |
|              |                  |            |                      |
|              |                  |            v                      |
|              |                  |  3. Se la pasa al modelo          |
|              |                  |     +-----------------------+     |
|              |                  |     |  Modelo: lee y piensa |     |
|              |                  |     +-----------------------+     |
|              |  4. respuesta    |            |                      |
|              | <--------------- |  <---------+                      |
+--------------+                  +-----------------------------------+

Si la llave está mal pegada, el paso 2 falla y ves un error de autenticación. Si ya usaste todo tu límite, el paso 2 también te frena, con un error de rate limit. Son los dos errores más comunes, y ahora sabes de dónde vienen.

Por qué un agente hace varias peticiones por encargo

Un chat hace una petición por cada mensaje tuyo. Un agente hace varias, porque trabaja en ciclo: piensa, usa una herramienta, mira el resultado y vuelve a pensar. Cada vez que "vuelve a pensar", es una petición nueva al modelo.

  Tu encargo: "Suma los gastos de expenses.csv"

  peticion 1 --> modelo: "Primero necesito leer expenses.csv"
                 OpenCode lee el archivo en tu laptop
  peticion 2 --> modelo: "Ya lo lei. Sumo por categoria y respondo"
                 OpenCode te muestra la respuesta

  Un encargo sencillo = 2 peticiones o mas.
  Un encargo que lee 3 archivos y escribe 1 = 5 peticiones o mas.

Por eso los planes gratis cuentan peticiones y no mensajes: a ellos les cuesta cada vez que el modelo trabaja.

Elige tu proveedor

Hay dos caminos en la nube que funcionan bien para el taller, y los dos te dan modelos gratuitos. Más abajo está un tercer camino, el camino C, para correr el modelo en tu propia laptop con LM Studio.

Si no quieres dar ningún dato de pago, usa OpenRouter. Es el camino que seguimos en vivo.

Sobre el límite de 50 peticiones al día: con lo que acabas de ver, un encargo puede gastar de 2 a 5 peticiones o más. Así que 50 alcanzan para la sesión y para practicar un rato, no para trabajar todo el día. Y el límite de 20 por minuto explica por qué a veces el agente se frena un momento si le pides muchas cosas seguidas. Si un día se te acaban, no es un error: es el plan gratis haciendo su trabajo.

Camino A: OpenRouter

1. Entra a openrouter.ai y crea una cuenta (puedes usar Google o GitHub).
2. En el menú de tu cuenta, entra a Keys.
3. Crea una llave nueva (Create Key) y ponle un nombre que reconozcas, por ejemplo agent-workshop. El nombre es solo para ti: te sirve para saber qué llave borrar si algún día se filtra.
4. Cópiala y guárdala en ese momento. La llave completa solo se muestra una vez. Si cierras la ventana sin copiarla, tendrás que crear otra: no pasa nada, pero te ahorras el paso.

La llave se ve más o menos así: sk-or-v1-xxxxxxxxxxxx. Ese prefijo sk-or-v1- es normal, y te sirve para reconocer de un vistazo que es una llave de OpenRouter.

Camino B: OpenCode Zen

1. Entra a opencode.ai/auth e inicia sesión.
2. Agrega tus datos de facturación. Los modelos marcados como gratuitos cuestan 0 y no generan cobro; Zen solo pide los datos para darte la llave.
3. Copia tu llave y guárdala.

Camino C: un modelo local con LM Studio (sin llave y sin internet)

Hasta aquí, el modelo vive en los servidores de un proveedor. Hay otra opción: descargar un modelo y correrlo en tu propia computadora. LM Studio es una aplicación gratuita que hace justo eso: baja el modelo, lo carga en la memoria de tu laptop y lo ofrece por una API igual a la de un proveedor, pero en tu máquina. OpenCode no nota la diferencia: le hablas al "mesero" de siempre, solo que la cocina está en tu casa.

Caminos A y B (en la nube)                Camino C (local)

  OpenCode ──internet──► proveedor         OpenCode ──► LM Studio
     ▲                   (usa tu llave)       ▲         (en tu laptop)
     │                        │               │              │
     └────── respuesta ◄──────┘               └── respuesta ◄┘

  Tus archivos viajan al proveedor         Tus archivos no salen de tu laptop

Cuándo elegirlo: si tienes una Mac con chip M (M1 o más nueva) o una PC con 16 GB de RAM o más, y quieres trabajar sin llave, sin límites y sin que tus archivos salgan de tu computadora. Cuándo no: si tu laptop tiene 8 GB de RAM, o si vas a instalarlo a última hora. La descarga pesa varios GB: hazla antes de la sesión, no durante. Si dudas, usa OpenRouter en vivo y prueba LM Studio después con calma: lo que aprendas en el taller funciona igual con los dos.

Paso a paso

1. Descarga LM Studio de lmstudio.ai e instálalo como cualquier aplicación.
2. Ábrelo, entra a la búsqueda de modelos y busca qwen3-8b. Descarga qwen/qwen3-8b. Es un modelo entrenado para usar herramientas, que es justo lo que necesita un agente.
3. Carga el modelo y, al cargarlo, busca la opción Context Length y súbela a 16384 o más. El contexto es el escritorio del modelo: si es muy chico, no le caben las instrucciones de OpenCode más tus archivos, y el agente falla al usar herramientas.
4. Entra a la pestaña Developer y activa Start server. Desde ese momento LM Studio responde en http://127.0.0.1:1234, una dirección que solo existe dentro de tu computadora.

Si prefieres la terminal, LM Studio trae el comando lms, que hace los pasos 3 y 4:

lms load qwen/qwen3-8b --context-length 16384
lms server start

Dile a OpenCode dónde está tu modelo

OpenCode no busca LM Studio solo: hay que decírselo en opencode.json. Estos bloques reescriben el opencode.json de tu carpeta de práctica: dejan los mismos permisos de antes (ask) y agregan LM Studio como proveedor. Pega el de tu sistema en la terminal.

Mac y Linux:

cd ~/agent-workshop
cat > opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "qwen/qwen3-8b": {
          "name": "Qwen3 8B (local)"
        }
      }
    }
  }
}
EOF

Windows (PowerShell):

Set-Location "$HOME\agent-workshop"
@'
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "qwen/qwen3-8b": {
          "name": "Qwen3 8B (local)"
        }
      }
    }
  }
}
'@ | Set-Content -Encoding ascii opencode.json

Qué significa cada parte nueva:

En la sesión, con este camino no necesitas /connect: no hay llave. Solo abre OpenCode, escribe /models y elige Qwen3 8B (local). LM Studio tiene que estar abierto con el servidor encendido.

Una nota sobre privacidad

Esto aplica a los caminos A y B; con el camino C tus archivos no salen de tu laptop. Recuerda el diagrama: en cada petición viaja tu encargo y el contenido de los archivos que el agente leyó. Varios modelos gratuitos usan lo que les escribes para entrenar sus modelos: así "pagas" el plan gratis. Para el taller trabajamos con datos de ejemplo, así que no importa. Como regla general, no le pases a un modelo gratuito datos personales ni información de tu trabajo.

Plan B, por si tu proveedor falla

Cada cuenta es un mundo. Si ninguno de los dos te funciona, Groq (console.groq.com) también tiene capa gratuita: cuenta, API Keys, Create API Key, copiar. OpenCode se conecta a Groq igual que a los otros dos. Esa es la ventaja de que OpenCode no traiga un modelo dentro: puedes cambiar de proveedor sin cambiar de herramienta.

Guarda tu llave con cuidado

• Guárdala en un gestor de contraseñas o en una nota privada.
• No la pegues en el chat de la videollamada ni la muestres en pantalla.
• Si alguna vez se te filtra, entra al proveedor, bórrala y crea otra. Es gratis y toma un minuto. Al borrarla, deja de funcionar para cualquiera que la tenga.

En la sesión la pegas una sola vez dentro de OpenCode, con el comando /connect. OpenCode la guarda en tu computadora y la agrega por su cuenta a cada petición.

Verifica que estás listo

• Tengo cuenta en OpenRouter (o en OpenCode Zen, o en Groq).
• Creé una llave y la guardé donde puedo encontrarla.
• (Solo camino C) LM Studio tiene qwen/qwen3-8b descargado, el servidor enciende y mi opencode.json ya incluye lmstudio.

Para comprobar que entendiste

Resumen

• El modelo es la IA; el proveedor la tiene en sus servidores; la API es la forma de pedirle cosas; tu llave te identifica en cada petición y por eso es secreta.
• Un agente hace varias peticiones por encargo, y por eso los planes gratis cuentan peticiones. OpenRouter te da modelos :free sin tarjeta, con 20 peticiones por minuto y 50 al día. OpenCode Zen también tiene modelos gratuitos, pero pide datos de facturación. Groq es el plan B.
• LM Studio corre un modelo en tu propia laptop: sin llave, sin límites y sin que tus archivos salgan, a cambio de una descarga de varios GB, una laptop con buena memoria y un modelo menos listo. Se prepara antes de la sesión.
• Con la llave guardada, ya estás listo para la sesión.

Recursos

• OpenRouter: límites de uso
• OpenCode: proveedores, incluido LM Studio
• LM Studio
• OpenCode Zen
• OpenCode: proveedores