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 SDKs ocultan la verdad. Añaden capas de abstracción que hacen que “Hello World” sea sencillo, pero que depurar un “Error 400” sea una pesadilla. Cuando aprendes el SDK, aprendes el SDK. Cuando aprendes la llamada HTTP en crudo, aprendes el protocolo que subyace a todos los SDKs.

Vamos a enviar un mensaje a Claude usando únicamente la biblioteca requests. Claude es el LLM insignia de Anthropic, uno de los modelos más capaces para tareas de programación.

Obtén una Clave de API

Para comunicarte con Claude, necesitas una clave de API. Es una cadena larga de caracteres que funciona como una contraseña vinculada a tu cuenta de facturación.

  1. Ve a la Consola de Anthropic.1
  2. Regístrate y añade un método de pago (mínimo $5 de crédito).
  3. Crea una nueva clave de API y nómbrala nanocode.
  4. Copia la clave (empieza 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 guardar esta clave. Nunca ponemos las claves directamente en el código.

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

1 touch .env

Ábrelo y pega tu clave:

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

Instalamos python-dotenv en el Capítulo 1 precisamente para este propósito: lee el archivo .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 cosas: 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:

Encabezado Valor Propósito
x-api-key Tu clave secreta Autenticación
anthropic-version 2023-06-01 Versión de la API
content-type application/json Formato

La Carga Útil

La “Messages API” 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 un content (el texto).

El Código

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

El Contexto: Estamos escribiendo código lineal y procedimental. Sin funciones, sin clases. Queremos ver el metal desnudo.

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)

El recorrido:

  • Línea 7: load_dotenv() encuentra el archivo .env y carga las variables en os.environ.
  • Línea 8: Obtenemos la clave de API. Nunca la codifiques directamente en el código.
  • Líneas 11-13: Comprobación básica de validez. Sin esto, una clave faltante provoca un confuso error NoneType en el diccionario de encabezados.
  • Línea 21: El encabezado anthropic-version es obligatorio. Si lo omites, la API te rechaza.
  • Línea 27: claude-sonnet-4-6 especifica el modelo que queremos.
  • Línea 28: max_tokens es obligatorio. Limita la longitud de la respuesta y evita costos descontrolados.
  • Línea 36: Enviamos la solicitud con un tiempo de espera de 2 minutos. Sin try/except — si la red está caída, deja que Python falle. Necesitas ver dónde ocurre el error.
  • Líneas 41-47: Verificamos el código de estado. 200 significa éxito (imprime el JSON con formato legible). Cualquier otro valor imprime el texto de error sin procesar para depuración.

Ejecútalo

1 python test_api.py

Si todo funciona, deberías 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
  }
}

Solución de problemas

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

Limpieza

Hemos demostrado que podemos hablar con el cerebro. Elimina test_api.py—hemos terminado con él.

An icon of a info-circle1

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

Aparte: Para monitorear tu gasto, revisa la pestaña de uso en la Anthropic Console. A principios de 2026, una sesión de programación típica con 20 o 30 intercambios cuesta entre $0.10 y $0.50 con Claude Sonnet. El campo usage al final del JSON de respuesta muestra el conteo exacto de tokens—podrías registrarlos para rastrear los costos de forma programática.

Conclusión

Eso es una llamada a la API en bruto: encabezados, payload JSON, procesamiento de la respuesta. Sin ninguna abstracción entre tú y el cable. Cuando algo falle (y fallará), sabrás exactamente en qué capa ocurrió porque solo hay una capa.

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

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

Previous

Capítulo 1: El Manifiesto de Cero Magia

Up next

Capítulo 3: El Bucle Infinito