Anthropic API Fundamentals

Template provided by VORLUX AI | vorluxai.com

---

API Overview

The Anthropic Messages API is the primary interface for interacting with Claude models. It follows a stateless request-response pattern where each call contains the full conversation context. Understanding its structure and features is essential for building reliable, cost-effective AI applications.

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

---

Authentication

All requests require an API key passed via the x-api-key header:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Security rules:

• Never embed API keys in client-side code
• Use environment variables or a secrets manager
• Rotate keys quarterly or immediately if exposed
• Set per-key spending limits in the Anthropic Console

---

Model Selection

Model	Best For	Input Cost (per 1M tokens)	Output Cost (per 1M tokens)
Claude Opus 4	Deep reasoning, complex analysis	$15.00	$75.00
Claude Sonnet 4	General coding, balanced tasks	$3.00	$15.00
Claude Haiku 3.5	Fast responses, classification, routing	$0.80	$4.00

Rule of thumb: Start with Haiku for prototyping and cost estimation. Upgrade to Sonnet for production. Reserve Opus for tasks where reasoning depth measurably improves output quality.

---

Prompt Caching

Prompt caching reduces costs by up to 90% for repeated system prompts and large context blocks. Mark cacheable blocks with cache_control:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a Docebo LMS expert. Here is the complete API reference: [20,000 tokens of documentation]",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "How do I create a course via API?"}]
}

Cache pricing: Cached input tokens cost 10% of standard input pricing. The cache has a 5-minute TTL — subsequent requests within that window hit the cache automatically.

When to use: Any system prompt or context block over 1,024 tokens that repeats across multiple requests. This includes RAG context, tool definitions, and few-shot examples.

---

Streaming

For user-facing applications, always stream responses to reduce perceived latency:

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain GDPR Article 5"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Streaming delivers the first token in ~200ms vs waiting 2-5 seconds for a complete response.

---

Tool Use (Function Calling)

Claude can call external tools and APIs when you define them in the request:

{
  "tools": [
    {
      "name": "get_hardware_specs",
      "description": "Retrieve specifications for a given hardware model",
      "input_schema": {
        "type": "object",
        "properties": {
          "model_name": {"type": "string", "description": "Hardware model name"}
        },
        "required": ["model_name"]
      }
    }
  ]
}

Claude returns a tool_use content block with the function name and arguments. Your application executes the function and sends the result back as a tool_result message. This pattern enables Claude to interact with databases, APIs, and real-time data.

---

Extended Thinking

For complex reasoning tasks, enable extended thinking to give Claude internal reasoning space:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [{"role": "user", "content": "Analyse this architecture for security vulnerabilities..."}]
}

The thinking tokens are billed at standard output rates but are not shown to the end user. Use this for code review, architectural analysis, and multi-step reasoning.

---

Cost Optimisation Patterns

1. Cache aggressively — Mark all static context with cache_control
2. Route by complexity — Use Haiku for simple tasks, Sonnet for complex ones
3. Set max_tokens precisely — Do not default to the maximum; set it to your expected output length + 20%
4. Batch when possible — Use the Batch API for non-interactive workloads at 50% cost reduction
5. Trim conversation history — Summarise old turns instead of sending the full thread

---

Need help building enterprise AI applications with the Anthropic API? Contact VORLUX AI for implementation support.

---

Versión Española

Fundamentos de la API de Anthropic

Plantilla proporcionada por VORLUX AI | vorluxai.com

---

Visión General de la API

La API de Mensajes de Anthropic es la interfaz principal para interactuar con los modelos Claude. Sigue un patrón de solicitud-respuesta sin estado donde cada llamada contiene el contexto completo de la conversación. Comprender su estructura y características es esencial para construir aplicaciones de IA fiables y rentables.

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

---

Autenticación

Todas las solicitudes requieren una clave API pasada mediante la cabecera x-api-key:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hola, Claude"}]
  }'

Reglas de seguridad:

• Nunca incluya claves API en código del lado del cliente
• Use variables de entorno o un gestor de secretos
• Rote las claves trimestralmente o inmediatamente si se exponen
• Establezca límites de gasto por clave en la Consola de Anthropic

---

Selección de Modelo

Modelo	Ideal Para	Coste Entrada (por 1M tokens)	Coste Salida (por 1M tokens)
Claude Opus 4	Razonamiento profundo, análisis complejo	$15,00	$75,00
Claude Sonnet 4	Programación general, tareas equilibradas	$3,00	$15,00
Claude Haiku 3.5	Respuestas rápidas, clasificación, enrutamiento	$0,80	$4,00

Regla general: Comience con Haiku para prototipado y estimación de costes. Upgrade a Sonnet para producción. Reserve Opus para tareas donde la profundidad de razonamiento mejore mediblemente la calidad.

---

Caché de Prompts

La caché de prompts reduce costes hasta un 90% para prompts del sistema repetidos y bloques de contexto grandes. Marque los bloques cacheables con cache_control:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "Eres un experto en Docebo LMS. Aquí está la referencia completa de la API: [20.000 tokens de documentación]",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "¿Cómo creo un curso vía API?"}]
}

Precio de caché: Los tokens de entrada cacheados cuestan el 10% del precio estándar de entrada. La caché tiene un TTL de 5 minutos — las solicitudes posteriores dentro de esa ventana acceden a la caché automáticamente.

Cuándo usar: Cualquier prompt del sistema o bloque de contexto superior a 1.024 tokens que se repita en múltiples solicitudes. Incluye contexto RAG, definiciones de herramientas y ejemplos few-shot.

---

Streaming

Para aplicaciones orientadas al usuario, siempre transmita las respuestas para reducir la latencia percibida:

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explica el Artículo 5 del RGPD"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

El streaming entrega el primer token en ~200ms frente a esperar 2-5 segundos por una respuesta completa.

---

Uso de Herramientas (Function Calling)

Claude puede llamar herramientas externas y APIs cuando las define en la solicitud:

{
  "tools": [
    {
      "name": "get_hardware_specs",
      "description": "Obtener especificaciones de un modelo de hardware dado",
      "input_schema": {
        "type": "object",
        "properties": {
          "model_name": {"type": "string", "description": "Nombre del modelo de hardware"}
        },
        "required": ["model_name"]
      }
    }
  ]
}

Claude devuelve un bloque de contenido tool_use con el nombre de la función y los argumentos. Su aplicación ejecuta la función y envía el resultado como un mensaje tool_result. Este patrón permite a Claude interactuar con bases de datos, APIs y datos en tiempo real.

---

Pensamiento Extendido

Para tareas de razonamiento complejo, habilite el pensamiento extendido para dar a Claude espacio de razonamiento interno:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [{"role": "user", "content": "Analiza esta arquitectura en busca de vulnerabilidades de seguridad..."}]
}

Los tokens de pensamiento se facturan a tarifas estándar de salida pero no se muestran al usuario final. Úselo para revisión de código, análisis arquitectónico y razonamiento multi-paso.

---

Patrones de Optimización de Costes

1. Cachee agresivamente — Marque todo el contexto estático con cache_control
2. Enrute por complejidad — Use Haiku para tareas simples, Sonnet para complejas
3. Establezca max_tokens con precisión — No use el máximo por defecto; establézcalo a su longitud de salida esperada + 20%
4. Agrupe cuando sea posible — Use la API de Batch para cargas no interactivas con 50% de reducción de coste
5. Recorte el historial de conversación — Resuma turnos antiguos en lugar de enviar el hilo completo

---

¿Necesita ayuda construyendo aplicaciones empresariales de IA con la API de Anthropic? Contacte con VORLUX AI para soporte de implementación.