Tu primera llamada a la API de Cohere

La Cooperativa Altos de Tacaná recibe por WhatsApp las mismas preguntas cada temporada: horarios del centro de acopio, requisitos para ser socio, cómo pedir un anticipo. Mariana, que lleva la parte administrativa y sabe algo de Python, quiere probar si un modelo de lenguaje puede ayudarle a redactar las respuestas. Antes de hablar de búsqueda o de RAG, necesita lo básico: una clave, un proyecto y una llamada que funcione.

En esta lección haces exactamente eso. Al final tendrás un módulo coop.py que vas a reutilizar durante todo el curso.

Al terminar podrás:

• crear una clave de prueba en Cohere y explicar sus límites;
• montar un proyecto de Python con uv y el SDK cohere;
• hacer una llamada a chat con ClientV2;
• leer el texto, finish_reason y usage de la respuesta, y reconocer los errores más comunes.

Paso 1: crea tu cuenta y tu clave de prueba

Entra a dashboard.cohere.com, crea una cuenta y ve a la página de claves de API (dashboard.cohere.com/api-keys). Ahí puedes crear dos tipos de clave:

• Clave de prueba (trial): gratuita y limitada en uso. Es la que usaremos en el curso.
• Clave de producción: para uso real, con límites de tasa más altos y cobro por consumo.

La documentación de límites de Cohere (consultada en octubre de 2026) indica que las claves de prueba tienen un tope de 1,000 llamadas a la API al mes, sumando todos los endpoints, y límites por minuto, por ejemplo 20 solicitudes por minuto en Chat y 10 en Rerank. Estas cifras pueden cambiar: revisa la página de límites antes de planear tus experimentos.

Mil llamadas alcanzan de sobra para el curso si trabajas con cuidado: agrupa textos en una sola llamada a embed, guarda los resultados en disco y no repitas llamadas que ya hiciste. En la lección 4.3 vemos cómo pasar a una clave de producción.

Tres reglas desde ya:

1. La clave nunca va dentro de un archivo .py.
2. La clave nunca se sube a Git, ni a un chat, ni a una captura de pantalla.
3. Si sospechas que se filtró, la borras en el panel y creas otra.

Paso 2: crea el proyecto con uv

uv es un gestor de proyectos y paquetes de Python. Si no lo tienes, instálalo siguiendo su documentación. Luego, en una terminal:

uv init cooperativa-rag
cd cooperativa-rag
uv add cohere numpy python-dotenv

uv add instala el SDK de Python de Cohere (cohere), numpy (lo usaremos desde el módulo 2) y python-dotenv para leer la clave desde un archivo .env. Si prefieres pip, la documentación de Cohere indica python -m pip install cohere --upgrade.

Paso 3: guarda la clave en .env

Dentro de cooperativa-rag crea un archivo .env con una línea:

CO_API_KEY=tu-clave-de-prueba

Y agrega .env a tu .gitignore:

.env

El cliente ClientV2 del SDK busca la clave en la variable de entorno CO_API_KEY cuando no le pasas api_key. También puedes pasarla explícitamente con cohere.ClientV2(api_key=...), que es lo que verás en muchos ejemplos de la documentación; nosotros preferimos la variable de entorno para no tener la clave cerca del código.

Paso 4: la primera llamada

Crea primera_llamada.py:

# primera_llamada.py
import cohere
from dotenv import load_dotenv

MODELO = "command-a-plus-05-2026"

load_dotenv()            # carga CO_API_KEY desde .env
co = cohere.ClientV2()   # usa la variable de entorno CO_API_KEY

respuesta = co.chat(
    model=MODELO,
    messages=[
        {
            "role": "user",
            "content": (
                "Soy socia de una cooperativa de café en Chiapas. En tres oraciones, "
                "explica qué es el café pergamino y por qué se mide su humedad."
            ),
        }
    ],
)

for bloque in respuesta.message.content:
    if bloque.type == "text":
        print(bloque.text)

print("---")
print("id:", respuesta.id)
print("finish_reason:", respuesta.finish_reason)
print("tokens facturados:", respuesta.usage.billed_units)

Ejecútalo:

uv run primera_llamada.py

Por qué este modelo

Usamos command-a-plus-05-2026 (Command A+) porque es el modelo que aparece en los ejemplos actuales de la documentación de Chat y, según su página en la documentación de Cohere, admite 48 idiomas, entre ellos el español y los demás idiomas de la Unión Europea. Hay alternativas, como command-a-03-2025 (Command A). Guardamos el nombre en la constante MODELO para cambiarlo en un solo lugar. Ten en cuenta un detalle que retomaremos en la lección 4.3: en la tabla de límites, Command A+ aparece con límite de producción "contactar a ventas", mientras que Command A tiene un límite de producción publicado. Con la clave de prueba ambos están disponibles.

Para ver la lista completa y vigente de modelos, consulta docs.cohere.com/docs/models o, desde código, el método co.models.list().

Paso 5: entiende la respuesta

co.chat devuelve un objeto con cuatro campos principales: id, finish_reason, message y usage.

message.content es una lista de bloques

El texto no está en un campo plano, sino en respuesta.message.content, una lista de bloques con un type. En muchos ejemplos verás respuesta.message.content[0].text, y funciona en el caso simple. Pero algunos modelos de Command pueden razonar antes de responder, y en ese caso la lista incluye bloques de tipo thinking además de los de tipo text. Por eso recorremos la lista y nos quedamos con los de texto. El razonamiento se controla con el parámetro thinking (por ejemplo {"type": "disabled"}); lo mencionamos en la lección 1.3.

Un ayudante que usarás en todo el curso:

def texto_de(respuesta) -> str:
    """Une el texto de todos los bloques de tipo text."""
    return "".join(b.text for b in respuesta.message.content if b.type == "text")

finish_reason dice por qué terminó

Los valores posibles en la API v2 son COMPLETE (terminó de forma natural), MAX_TOKENS (se cortó por el tope de salida), STOP_SEQUENCE (encontró una secuencia de paro), TOOL_CALL (quiere usar una herramienta, lección 4.1), ERROR y TIMEOUT. Revísalo antes de usar el texto: una respuesta cortada a la mitad puede ser peor que ninguna.

usage dice cuánto consumiste

respuesta.usage tiene dos partes principales:

• billed_units: lo que se factura (input_tokens, output_tokens y, en otros endpoints, unidades como search_units).
• tokens: los tokens que el modelo procesó como entrada y los que produjo como salida. Este conteo no siempre coincide con lo facturado, así que compara ambos en tus primeras pruebas.

También puede aparecer cached_tokens, el número de tokens del prompt que aprovecharon la caché de inferencia.

Para el costo, usa billed_units y multiplica por el precio vigente de tu modelo, que encuentras en cohere.com/pricing. No copiamos precios en el curso porque cambian; en la lección 4.3 armamos un registro de consumo que solo necesita que pongas los precios del día.

Si algo sale mal

El SDK lanza excepciones con nombres claros, todas derivadas de ApiError (en cohere.core.api_error):

• UnauthorizedError (401): la clave es incorrecta o no se cargó. Revisa que el archivo se llame exactamente .env y esté en la carpeta donde ejecutas el script.
• NotFoundError (404) o BadRequestError (400): el nombre del modelo está mal escrito o falta un campo. Lee el mensaje: suele decir qué falla.
• TooManyRequestsError (429): superaste el límite por minuto o el mensual de tu clave de prueba. Espera o reduce la frecuencia.

import cohere
from cohere.core.api_error import ApiError

try:
    respuesta = co.chat(model=MODELO, messages=[{"role": "user", "content": "Hola"}])
except cohere.TooManyRequestsError:
    print("Límite alcanzado: espera un minuto o revisa tu cuota mensual.")
except ApiError as e:
    print("Error de la API:", e.status_code, e.body)

En la lección 4.3 agregamos reintentos con espera progresiva.

Una versión reutilizable

Crea coop.py. Este módulo crece a lo largo del curso:

# coop.py
import cohere
from dotenv import load_dotenv

MODELO = "command-a-plus-05-2026"

load_dotenv()
co = cohere.ClientV2()

SISTEMA = (
    "Eres el asistente de la Cooperativa Cafetalera Altos de Tacaná, en Unión Juárez, "
    "Chiapas. Respondes a socios productores de café, en español claro y breve, "
    "tratándolos de usted. Si no sabes algo con certeza, lo dices."
)


def texto_de(respuesta) -> str:
    return "".join(b.text for b in respuesta.message.content if b.type == "text")


def preguntar(pregunta: str, max_tokens: int = 600) -> str:
    respuesta = co.chat(
        model=MODELO,
        messages=[
            {"role": "system", "content": SISTEMA},
            {"role": "user", "content": pregunta},
        ],
        max_tokens=max_tokens,
    )
    if respuesta.finish_reason == "MAX_TOKENS":
        print("Aviso: la respuesta se cortó por max_tokens")
    b = respuesta.usage.billed_units
    print(f"[{respuesta.id}] entrada={b.input_tokens} salida={b.output_tokens}")
    return texto_de(respuesta)


if __name__ == "__main__":
    print(preguntar("¿Qué cuidados necesita el café pergamino durante el secado?"))

Observa el mensaje con rol system: le da al modelo su papel y el tono. Lo vemos a fondo en la siguiente lección.

Ahora haz una prueba reveladora: pregunta preguntar("¿Hasta qué mes recibe café el centro de acopio de la cooperativa?"). El modelo no tiene el reglamento, así que lo correcto es que diga que no lo sabe. Si inventa un mes, acabas de ver en vivo el problema que resolveremos con RAG.

Práctica

Dedica 25 minutos y no más de 15 llamadas a la API.

1. Crea tu clave de prueba, guárdala en .env y confirma que .env está en .gitignore.
2. Crea el proyecto con uv init y uv add cohere numpy python-dotenv, y ejecuta primera_llamada.py.
3. Imprime respuesta.message.content completo. Anota qué tipos de bloque aparecen.
4. Llama a co.chat con max_tokens=20 y observa el valor de finish_reason y cómo queda el texto.
5. Con coop.py, haz cinco preguntas de socios: tres de conocimiento general (secado, roya, cosecha) y dos sobre la cooperativa en particular (horarios, anticipos). Para cada una anota tokens facturados de entrada y de salida y si la respuesta es verificable o inventada.

Resumen

• La clave de prueba es gratuita y limitada (en octubre de 2026: 1,000 llamadas al mes y límites por minuto); se crea en dashboard.cohere.com/api-keys.
• ClientV2 lee la clave de CO_API_KEY; la guardamos en .env fuera de Git.
• co.chat requiere model y messages; guardamos el modelo en la constante MODELO.
• El texto está en respuesta.message.content, una lista de bloques: filtra los de tipo text.
• finish_reason explica por qué terminó la respuesta y usage.billed_units dice qué se factura.

Quiz