Capítulo 2: La Solicitud sin Procesar

La mayoría de los tutoriales te dirán que ejecutes pip install anthropic. No vamos a hacer eso.

Los SDK ocultan la verdad. Añaden capas de abstracción que hacen que un “Hola Mundo” sea fácil pero convierten la depuración de un “Error 400” en una pesadilla. Cuando aprendes el SDK, aprendes el SDK. Cuando aprendes la llamada HTTP sin procesar, aprendes el protocolo que está debajo de cada SDK.

Vamos a enviar un mensaje a Claude usando solamente la biblioteca requests. Claude es el modelo de lenguaje insignia de Anthropic—uno de los modelos más capaces para tareas de programación.

Obtener una Clave API

Para hablar con Claude, necesitas una Clave API. Esta es una larga cadena de caracteres que actúa como tu tarjeta de crédito.

  1. Ve a la Consola de Anthropic.1
  2. Regístrate y añade un método de pago (crédito mínimo de $5).
  3. Crea una nueva Clave API y nómbrala nanocode.
  4. Copia la clave (comienza con sk-ant-...).
An icon of a warning1

Advertencia: Trata esta clave como una contraseña. Cualquiera que la tenga puede gastar tu dinero.

La Bóveda (.env)

Necesitamos un lugar seguro para almacenar esta clave. Nunca ponemos claves directamente en el código.

Crea un archivo llamado .env en la raíz de tu proyecto:

1 touch .env

Ábralo y pegue su clave:

1 ANTHROPIC_API_KEY=sk-ant-api03-...

Instalamos python-dotenv en el Capítulo 1 exactamente para este propósito—lee .env y carga los valores en os.environ.

La Anatomía de una Solicitud

Para comunicarnos con un LLM, enviamos una solicitud HTTP POST a:

https://api.anthropic.com/v1/messages

Esta solicitud necesita tres elementos: autenticación en los encabezados (tu clave de API), configuración en el cuerpo (qué modelo, cuántos tokens) y el mensaje en sí.

Los Encabezados

Anthropic requiere tres encabezados:

Header Value Purpose
x-api-key Tu clave secreta Autenticación
anthropic-version 2023-06-01 Versión de API
content-type application/json Formato

La Carga Útil

La “API de Mensajes” espera una lista de diccionarios de mensajes:

1 "messages": [
2     {"role": "user", "content": "Hello, world!"}
3 ]

Cada mensaje tiene un role (ya sea "user" o "assistant") y content (el texto).

El Código

Crea un archivo llamado test_api.py. Esta es una “prueba de humo” para comprobar que nuestra conexión funciona. Lo eliminaremos más tarde.

El Contexto: Estamos escribiendo código lineal y procedimental. Sin funciones, sin clases. Queremos ver el nivel más básico.

El Código:

 1 import os
 2 import requests
 3 import json
 4 from dotenv import load_dotenv
 5 
 6 # 1. Load the vault
 7 load_dotenv()
 8 api_key = os.getenv("ANTHROPIC_API_KEY")
 9 
10 # Basic check so we don't crash with a confusing "NoneType" error later
11 if not api_key:
12     print("Error: ANTHROPIC_API_KEY not found in .env")
13     exit(1)
14 
15 # 2. Define the target
16 url = "https://api.anthropic.com/v1/messages"
17 
18 # 3. Authenticate
19 headers = {
20     "x-api-key": api_key,
21     "anthropic-version": "2023-06-01",
22     "content-type": "application/json"
23 }
24 
25 # 4. Construct the payload
26 payload = {
27     "model": "claude-sonnet-4-6",
28     "max_tokens": 4096,
29     "messages": [
30         {"role": "user", "content": "Hello, are you ready to code?"}
31     ]
32 }
33 
34 # 5. Fire! (No safety net)
35 print("📡 Sending request to Claude...")
36 response = requests.post(url, headers=headers, json=payload, timeout=120)
37 
38 # 6. Inspect the raw result
39 print(f"Status: {response.status_code}")
40 
41 if response.status_code == 200:
42     # Success: Print the beautiful JSON
43     print("Response:")
44     print(json.dumps(response.json(), indent=2))
45 else:
46     # Failure: Print the ugly raw text so we can debug
47     print("Error:", response.text)

La Explicación Detallada:

  • Línea 7: load_dotenv() encuentra el archivo .env y carga las variables en os.environ.
  • Línea 8: Obtenemos la clave API. Nunca la codifiques directamente en el código.
  • Líneas 11-13: Validación básica. Sin esto, una clave faltante causa un error confuso de NoneType en el diccionario de headers.
  • Línea 21: El header anthropic-version es obligatorio. Si lo omites, la API te rechazará.
  • Línea 27: claude-sonnet-4-6 especifica qué modelo queremos.
  • Línea 28: max_tokens es requerido. Limita la longitud de la respuesta y previene costos descontrolados.
  • Línea 36: Enviamos la petición con un timeout de 2 minutos. Sin try/except—si la red está caída, dejamos que Python falle. Necesitas ver dónde falla.
  • Líneas 41-47: Verificamos el código de estado. 200 significa éxito (impresión formateada del JSON). Cualquier otro código significa que imprimimos el texto del error en bruto para depuración.

Ejecútalo

1 python test_api.py

Si todo funciona, debería ver:

Status: 200
Response:
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! Yes, I'm ready to code..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 81
  }
}

Resolución de problemas

Error Causa Solución
401 Unauthorized Clave API incorrecta Verifica que .env se está cargando. Imprime os.environ.get("ANTHROPIC_API_KEY") para verificar.
400 Bad Request JSON mal formado ¿Olvidaste max_tokens? ¿Es messages una lista?
429 Rate Limit Demasiadas solicitudes o sin créditos Espera, o añade créditos a tu cuenta.

Limpieza

Probamos que podemos hablar con el cerebro. Elimina test_api.py: ya no lo necesitamos.

An icon of a info-circle1

Nota al margen: Este test_api.py es código desechable, una prueba de humo de un solo uso. Las pruebas automatizadas reales (con FakeBrain y pytest) llegan en el Capítulo 3. Siempre deberías eliminar este archivo después de verificar que tu conexión API funciona.
An icon of a info-circle1

Nota al margen: Para monitorear tu gasto, revisa la pestaña de Uso en la Consola de Anthropic. A principios de 2026, una sesión típica de programación con 20-30 intercambios cuesta entre $0.10-$0.50 con Claude Sonnet. El campo usage en la parte inferior del JSON de respuesta muestra el conteo exacto de tokens; podrías registrar estos datos para hacer un seguimiento programático de los costos.

Conclusión

Esa es una llamada API sin procesar: encabezados, carga útil JSON, análisis de respuesta. No hay abstracción entre tú y el nivel bajo. Cuando algo se rompa (y se romperá), sabrás exactamente qué capa falló porque solo hay una capa.

Un problema: Claude tiene amnesia total. Cada solicitud es una pizarra en blanco. Vamos a simular la memoria reproduciendo todo el historial de conversación en cada turno.

  1. https://console.anthropic.com/settings/keys↩︎

Up next

Capítulo 3: El Bucle Infinito