Cómo usar la API de IA con Python: de tu primera llamada a procesar miles de textos

Los chats son perfectos para trabajar de uno en uno. Pero si tienes que clasificar 2.000 comentarios de clientes, extraer datos de 500 facturas o generar fichas para todo un catálogo, copiar y pegar deja de ser una opción. Para eso existen las APIs de los modelos de lenguaje: te permiten usar la IA desde tu propio código, integrarla en tus sistemas y procesar grandes volúmenes de forma automática.

Esta lección usa Python. Si nunca has programado, puedes leerla para entender cómo funciona y volver después de hacer nuestro curso de Python desde cero (con las primeras 8 lecciones es suficiente).

Qué es una API y cómo se cobra

Una API (interfaz de programación de aplicaciones) es una puerta para que un programa hable con otro. En lugar de escribir en la página del chat, tu programa envía el mensaje por internet al proveedor (Anthropic, OpenAI, Google y otros), el modelo lo procesa y la respuesta vuelve a tu programa como datos.

Recuerda de la lección 2 que los modelos trabajan con tokens (fragmentos de palabra). En la API pagas por los tokens que envías (entrada) y por los que el modelo genera (salida); la salida suele costar varias veces más que la entrada. Los precios dependen del modelo: los más potentes cuestan más y los pequeños son mucho más baratos y rápidos. Consulta siempre la página de precios del proveedor antes de un proyecto grande.

Preparación: cuenta, clave y librería

1. Crea una cuenta de desarrollador en la consola del proveedor que elijas y añade un método de pago o crédito. En esta lección usamos la API de Claude (Anthropic) como ejemplo; las de OpenAI y Google funcionan de forma muy parecida.
2. Configura un límite de gasto mensual en la consola. Es tu red de seguridad si un programa entra en un bucle.
3. Genera una clave de API (API key). Es como una contraseña: quien la tenga puede gastar tu dinero.
4. Instala la librería oficial en tu entorno virtual: pip install anthropic

Guarda la clave en una variable de entorno

Nunca escribas la clave dentro del código: acabaría en un correo, en GitHub o en una captura de pantalla. Guárdala en una variable de entorno, que la librería lee automáticamente:

# Windows (PowerShell), para la sesión actual
$env:ANTHROPIC_API_KEY="tu-clave-aquí"

# macOS y Linux
export ANTHROPIC_API_KEY="tu-clave-aquí"

Tu primera llamada

# primer_mensaje.py
import anthropic

client = anthropic.Anthropic()   # lee la clave de ANTHROPIC_API_KEY

respuesta = client.messages.create(
    model="claude-sonnet-5-5",     # consulta los modelos vigentes en la documentación
    max_tokens=500,
    system="Eres un asistente que responde en español, de forma breve y clara.",
    messages=[
        {"role": "user", "content": "Explica qué es una API en 3 frases."}
    ],
)

print(respuesta.content[0].text)
print("Tokens:", respuesta.usage.input_tokens, "de entrada,",
      respuesta.usage.output_tokens, "de salida")

Los parámetros clave:

• model: qué modelo usar. Los nombres cambian cuando salen versiones nuevas; la documentación del proveedor tiene la lista actualizada.
• max_tokens: el máximo de tokens que puede generar. Controla la longitud y el costo de la respuesta.
• system: las instrucciones permanentes, como las del asistente personalizado de la lección 8.
• messages: la conversación, como una lista de mensajes con su rol (user para ti, assistant para el modelo).

La respuesta llega como un objeto: el texto está en respuesta.content[0].text y el consumo en respuesta.usage, que te permite calcular el costo de cada llamada.

Una conversación con memoria

La API no recuerda nada entre llamadas: cada una es independiente. Para mantener una conversación, tu programa debe enviar el historial completo cada vez. Así funciona por dentro cualquier chat:

# chat.py
import anthropic

client = anthropic.Anthropic()
historial = []

while True:
    pregunta = input("Tú: ").strip()
    if pregunta.lower() in ("salir", "exit", ""):
        break
    historial.append({"role": "user", "content": pregunta})

    respuesta = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=800,
        system="Eres un tutor de finanzas personales. Responde en español, con ejemplos.",
        messages=historial,
    )
    texto = respuesta.content[0].text
    historial.append({"role": "assistant", "content": texto})
    print(f"\nIA: {texto}\n")

Fíjate en la consecuencia: cada mensaje nuevo reenvía toda la conversación, así que las conversaciones largas consumen cada vez más tokens de entrada. Es la misma "ventana de contexto" de la lección 2, ahora con precio visible.

Procesamiento por lotes: clasificar un CSV completo

Este es el caso de uso con más retorno. Partimos de un archivo comentarios.csv con dos columnas, id y comentario, y queremos añadir a cada fila el sentimiento, el tema y un resumen. Combinamos lo que viste en la lección 5 (salidas en JSON) con el manejo de archivos y errores del curso de Python:

# clasificar.py
import csv
import json
import time

import anthropic

MODELO = "claude-sonnet-5-5"
CATEGORIAS = {"Precio", "Atención", "Envío", "Calidad", "Otro"}

client = anthropic.Anthropic(max_retries=3)   # reintenta solo si hay errores temporales

INSTRUCCIONES = """Clasificas comentarios de clientes de una tienda online.
Responde SOLO con JSON válido, sin texto adicional, con esta forma:
{"sentimiento": "Positivo|Negativo|Mixto", "tema": "Precio|Atención|Envío|Calidad|Otro", "resumen": "máximo 12 palabras"}"""


def clasificar(comentario):
    respuesta = client.messages.create(
        model=MODELO,
        max_tokens=200,
        system=INSTRUCCIONES,
        messages=[{"role": "user", "content": f"<comentario>{comentario}</comentario>"}],
    )
    texto = respuesta.content[0].text.strip()
    # Por si el modelo envuelve el JSON en un bloque de código
    texto = texto.removeprefix("```json").removeprefix("```").removesuffix("```").strip()
    datos = json.loads(texto)
    if datos.get("tema") not in CATEGORIAS:   # validar: nunca confíes a ciegas
        datos["tema"] = "REVISAR"
    uso = respuesta.usage.input_tokens + respuesta.usage.output_tokens
    return datos, uso


def main():
    with open("comentarios.csv", newline="", encoding="utf-8") as f:
        filas = list(csv.DictReader(f))

    resultados, tokens = [], 0
    for i, fila in enumerate(filas, start=1):
        try:
            datos, uso = clasificar(fila["comentario"])
            tokens += uso
        except json.JSONDecodeError:
            datos = {"sentimiento": "REVISAR", "tema": "REVISAR", "resumen": "Respuesta no válida"}
        except anthropic.APIError as e:
            print(f"Fila {i}: error de la API ({e.__class__.__name__}), se marca para revisar")
            datos = {"sentimiento": "REVISAR", "tema": "REVISAR", "resumen": ""}
        resultados.append({**fila, **datos})
        print(f"{i}/{len(filas)} · {datos['tema']}")
        time.sleep(0.5)   # pausa breve para no saturar la API

    with open("comentarios_clasificados.csv", "w", newline="", encoding="utf-8-sig") as f:
        escritor = csv.DictWriter(f, fieldnames=list(resultados[0].keys()))
        escritor.writeheader()
        escritor.writerows(resultados)

    print(f"Listo: {len(resultados)} comentarios · {tokens} tokens usados")


if __name__ == "__main__":
    main()

Las decisiones de diseño que hacen fiable el script

• Instrucciones con formato exacto y categorías cerradas: el resultado se puede analizar después con Excel o pandas.
• Validación: si el modelo devuelve un tema que no está en la lista, se marca "REVISAR" en lugar de aceptarlo.
• Errores controlados: un JSON inválido o un fallo de conexión no detiene el proceso; la fila queda marcada para revisión manual.
• Reintentos y pausas: max_retries repite automáticamente las llamadas que fallan por errores temporales, y la pausa evita superar los límites de velocidad.
• Registro de tokens: sabes cuánto costó cada ejecución.
• utf-8-sig al guardar: el CSV se abre en Excel con las tildes correctas.

Controlar los costos

Antes de procesar miles de filas, estima el costo con una prueba pequeña. Ejemplo con precios hipotéticos de 3 USD por millón de tokens de entrada y 15 USD por millón de salida (consulta los precios reales de tu modelo):

Clasificar mil comentarios a mano puede llevar un día de trabajo; por API, unos minutos y un costo muy bajo. Aun así, sigue estas reglas:

• Prueba primero con 20 filas y revisa los resultados antes de lanzar el archivo completo.
• Elige el modelo más pequeño que haga bien la tarea: para clasificar o extraer datos simples, un modelo rápido y barato suele bastar; reserva los más potentes para razonamientos complejos.
• Limita max_tokens a lo que realmente necesitas.
• Mantén el límite de gasto configurado en la consola.
• Para volúmenes grandes que no son urgentes, los proveedores ofrecen procesamiento por lotes (batch) con descuento a cambio de esperar unas horas, y caché de prompts para abaratar instrucciones largas que se repiten. Consulta su documentación cuando tus volúmenes crezcan.

Verificar la calidad del resultado

Un proceso automático que se equivoca en el 10% de los casos puede ser muy útil o un desastre, según lo que decidas con él. Mide antes de confiar:

1. Clasifica a mano una muestra de 50 filas (tu "respuesta correcta").
2. Compara con lo que dio el script y calcula el porcentaje de aciertos.
3. Revisa los errores: ¿falta una categoría?, ¿hay casos ambiguos?, ¿ayudaría añadir ejemplos a las instrucciones (lección 5)?
4. Ajusta las instrucciones y vuelve a medir con la misma muestra.
5. Una vez en marcha, revisa siempre las filas "REVISAR" y una muestra aleatoria periódica.

INSTRUCCIONES = """Extraes datos de mensajes de clientes que hacen pedidos.
Responde SOLO con JSON válido con esta forma:
{"nombre_producto": "texto o null", "cantidad": número o null,
 "urgente": "sí|no", "requiere_humano": "sí|no"}
Reglas:
- Usa null si el dato no aparece. No supongas cantidades.
- urgente = "sí" solo si el cliente menciona una fecha cercana o la palabra urgente.
- requiere_humano = "sí" si es un reclamo, una pregunta que no es un pedido
  o el mensaje es ambiguo."""


def validar(datos):
    if datos.get("urgente") not in ("sí", "no"):
        datos["urgente"] = "REVISAR"
    if datos.get("requiere_humano") not in ("sí", "no"):
        datos["requiere_humano"] = "REVISAR"
    cantidad = datos.get("cantidad")
    if cantidad is not None and not isinstance(cantidad, (int, float)):
        datos["cantidad"] = "REVISAR"
    return datos

# En clasificar(): sustituye la validación de "tema" por
#     datos = validar(json.loads(texto))
# y en main() lee fila["mensaje"] en lugar de fila["comentario"].

Resumen

• La API permite usar los modelos desde tu código, con pago por tokens de entrada y salida.
• Guarda la clave en una variable de entorno y configura un límite de gasto.
• messages.create recibe el modelo, el límite de tokens, las instrucciones (system) y los mensajes.
• La API no tiene memoria: para conversar, envía el historial completo.
• Para procesar por lotes: formato exacto, validación, errores controlados, prueba pequeña y medición de la calidad.

En la próxima lección pasarás de tus propios proyectos a la organización: cómo implementar la IA en una empresa, desde elegir los casos de uso hasta medir el retorno.