Guía básica de uso de la API para Claude

Esta guía está diseñada para darle a Claude los conceptos básicos del uso de la API de Claude. Ofrece explicaciones y ejemplos de los ID de modelo/la API básica de mensajes, el uso de herramientas, el streaming, el pensamiento y nada más.

Modelos

Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5.5 pricing: Claude Fable 5.2: claude-fable-5-2
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001

Llamar a la API

Solicitud y respuesta básicas

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Múltiples turnos de conversación

La Messages API es “stateless” (sin estado), lo que significa que siempre envías el historial completo de la conversación a la API. Puedes usar este patrón para construir una conversación a lo largo del tiempo. Los turnos de conversación anteriores no necesariamente tienen que provenir realmente de Claude. Puedes usar mensajes assistant sintéticos.

Con los “message threads” (hilos de mensajes), en beta, la API puede conservar la conversación, de modo que cada solicitud posterior envíe solo los mensajes nuevos. Un hilo expira 5 minutos después de su última solicitud y se elimina como máximo 1 hora después de su último uso.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Prellenar la respuesta de Claude

Puedes prellenar (“prefill”) parte de la respuesta de Claude en la última posición de la lista de mensajes de entrada. Usa esta técnica para dar forma a la respuesta de Claude. El siguiente ejemplo usa "max_tokens": 1 para obtener de Claude una única respuesta de opción múltiple.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)

Visión

Claude puede leer tanto texto como imágenes en las solicitudes. Para las imágenes se admiten los tipos de origen base64 y url, junto con los tipos de medios image/jpeg, image/png, image/gif e image/webp.

import anthropic
import base64
import httpx2

# Opción 1: imagen codificada en Base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message.content if block.type == "text"))

# Opción 2: imagen referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))

Pensamiento

El pensamiento (“thinking”) a veces puede ayudar a Claude con tareas muy difíciles. El mecanismo actual es el pensamiento adaptativo (thinking: {"type": "adaptive"}): Claude determina cuándo y cuánto pensar, y tú diriges la profundidad del pensamiento con el parámetro effort en lugar de con un presupuesto de tokens. El pensamiento adaptativo es compatible con los modelos Claude 4.6 y posteriores y con Claude Mythos Preview. En los modelos Claude 5 y posteriores y en Claude Mythos Preview, el pensamiento está activado de forma predeterminada cuando se omite el parámetro thinking.

El pensamiento es compatible con los siguientes modelos:

• Claude Fable 5.2 (claude-fable-5-2, solo pensamiento adaptativo, siempre activado)
• Claude Mythos 5.2 (claude-mythos-5-2, solo pensamiento adaptativo, siempre activado)
• Claude Opus 5.5 (claude-opus-5-5, solo pensamiento adaptativo, siempre activado)
• Claude Sonnet 5.5 (claude-sonnet-5-5, solo pensamiento adaptativo, activado de forma predeterminada; thinking: {"type": "disabled"} devuelve un error 400, así que envía thinking: {"type": "between_tools"} para desactivar el pensamiento inicial)
• Claude Haiku 5.5 (claude-haiku-5-5, solo pensamiento adaptativo, activado de forma predeterminada)
• Claude Fable 5.1 (claude-fable-5-1, solo pensamiento adaptativo, siempre activado)
• Claude Mythos 5.1 (claude-mythos-5-1, solo pensamiento adaptativo, siempre activado)
• Claude Fable 5 (claude-fable-5, solo pensamiento adaptativo, siempre activado)
• Claude Mythos 5 (claude-mythos-5, solo pensamiento adaptativo, siempre activado)
• Claude Opus 5 (claude-opus-5, solo pensamiento adaptativo, activado de forma predeterminada)
• Claude Sonnet 5 (claude-sonnet-5, solo pensamiento adaptativo, activado de forma predeterminada)
• Claude Opus 4.8 (claude-opus-4-8, solo pensamiento adaptativo)
• Claude Opus 4.7 (claude-opus-4-7, solo pensamiento adaptativo)
• Claude Opus 4.6 (claude-opus-4-6, pensamiento adaptativo o pensamiento manual heredado)
• Claude Sonnet 4.6 (claude-sonnet-4-6, pensamiento adaptativo o pensamiento manual heredado)
• Claude Opus 4.5 (claude-opus-4-5-20251101, solo pensamiento manual heredado)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, obsoleto, solo pensamiento manual heredado)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, solo pensamiento manual heredado)

Cómo funciona el pensamiento

Cuando el pensamiento está activado, Claude crea bloques de contenido thinking en los que genera su razonamiento interno. La respuesta de la API incluye bloques de contenido thinking, seguidos de bloques de contenido text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# La respuesta contiene bloques de pensamiento resumidos y bloques de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

El pensamiento extendido manual (thinking: {"type": "enabled", "budget_tokens": N}) es el mecanismo heredado. Solo funciona en los modelos Claude 4 a 4.6 que admiten pensamiento; los modelos Claude 4.7 y posteriores rechazan type: enabled con un error 400 y usan en su lugar el pensamiento adaptativo. Con el pensamiento extendido manual, budget_tokens establece el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno; el límite se aplica a los tokens de pensamiento completos, no a la salida resumida. A menos que uses el pensamiento intercalado, budget_tokens debe ser menor que max_tokens para que Claude tenga espacio para escribir su respuesta una vez completado el pensamiento.

Pensamiento con uso de herramientas

El pensamiento puede usarse junto con el “tool use” (uso de herramientas), lo que permite a Claude razonar sobre la selección de herramientas y el procesamiento de resultados.

Limitaciones importantes:

1. Limitación de la elección de herramientas: Con el pensamiento extendido manual (thinking: {"type": "enabled"}), solo se admite tool_choice: {"type": "auto"} (predeterminado) o tool_choice: {"type": "none"}. El pensamiento adaptativo acepta el uso forzado de herramientas, excepto en los modelos enumerados en Forzar el uso de herramientas. Donde se acepta, una llamada forzada a una herramienta omite el pensamiento: la respuesta comienza con la llamada a la herramienta y no tiene ningún bloque thinking.
2. Conservar los bloques de pensamiento: Durante el uso de herramientas, debes devolver a la API los bloques thinking del último mensaje del asistente.

Conservar los bloques de pensamiento

import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Primera solicitud: Claude responde con pensamiento y una solicitud de herramienta
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrae el bloque de pensamiento y el bloque de uso de herramientas
thinking_block = next(
    (block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
    (block for block in response.content if block.type == "tool_use"), None
)

# Segunda solicitud: incluye el bloque de pensamiento y el resultado de la herramienta
continuation = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Observa que se pasa el thinking_block además del tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

for block in continuation.content:
    if block.type == "text":
        print(block.text)

Pensamiento intercalado

El “interleaved thinking” (pensamiento intercalado) permite a Claude pensar entre llamadas a herramientas, razonando sobre los resultados de las herramientas antes de determinar el siguiente paso.

En los modelos más antiguos que usan pensamiento extendido manual (modelos Claude 4, 4.5 y Sonnet 4.6), habilita el pensamiento intercalado agregando el encabezado beta interleaved-thinking-2025-05-14 a tu solicitud de API:

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "text":
            print(f"Response: {block.text}")

Con el pensamiento intercalado y SOLO con el pensamiento intercalado (no con el pensamiento extendido manual normal), budget_tokens puede superar el parámetro max_tokens, ya que en este caso budget_tokens representa el presupuesto total de todos los bloques de pensamiento dentro de un turno del asistente.

Uso de herramientas

Especificar herramientas de cliente

Las herramientas de cliente se especifican en el parámetro de nivel superior tools de la solicitud de API. Cada definición de herramienta incluye:

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Mejores prácticas para las definiciones de herramientas

Proporciona descripciones extremadamente detalladas. Este es, con diferencia, el factor más importante en el rendimiento de las herramientas. Tus descripciones deben explicar cada detalle de la herramienta, incluyendo:

• Qué hace la herramienta
• Cuándo debe usarse (y cuándo no)
• Qué significa cada parámetro y cómo afecta al comportamiento de la herramienta
• Cualquier advertencia o limitación importante

Considera usar input_examples para herramientas complejas. Para herramientas con objetos anidados, parámetros opcionales o entradas sensibles al formato, puedes proporcionar ejemplos concretos usando el campo input_examples (beta). Esto le muestra a Claude los patrones de entrada esperados. Consulta Proporcionar ejemplos de uso de herramientas para obtener más detalles.

Ejemplo de una buena descripción de herramienta:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Controlar la salida de Claude

Forzar el uso de herramientas

Puedes obligar a Claude a usar una herramienta específica indicando la herramienta en el campo tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

Al trabajar con el parámetro tool_choice, hay cuatro opciones posibles:

• auto permite que Claude decida si llamar o no a alguna de las herramientas proporcionadas (predeterminado).
• any le indica a Claude que debe usar una de las herramientas proporcionadas.
• tool obliga a Claude a usar siempre una herramienta en particular.
• none impide que Claude use cualquier herramienta.

En Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1, any y tool devuelven un error 400. Deja tool_choice en auto y establece "strict": true en la definición de la herramienta para garantizar que cualquier llamada que haga Claude coincida con el input_schema de la herramienta. Consulta Uso estricto de herramientas.

Salida JSON

Las herramientas no tienen por qué ser necesariamente funciones de cliente. Puedes usar herramientas siempre que quieras que el modelo devuelva una salida JSON que siga un esquema proporcionado.

Uso de herramientas en paralelo

De forma predeterminada, Claude puede usar varias herramientas para responder a una consulta del usuario. Puedes desactivar este comportamiento estableciendo disable_parallel_tool_use=true.

Manejar los bloques de contenido de uso de herramientas y de resultados de herramientas

Manejar los resultados de las herramientas de cliente

La respuesta tiene un stop_reason de tool_use y uno o más bloques de contenido tool_use que incluyen:

• id: Un identificador único para este bloque de uso de herramientas en particular.
• name: El nombre de la herramienta que se está usando.
• input: Un objeto que contiene la entrada que se pasa a la herramienta.

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Cuando recibas una respuesta de uso de herramientas, debes:

1. Extraer name, id e input del bloque tool_use.
2. Ejecutar la herramienta real en tu código base que corresponda a ese nombre de herramienta.
3. Continuar la conversación enviando un nuevo mensaje con un tool_result:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Manejar el motivo de detención max_tokens

Si la respuesta de Claude se corta porque alcanza el límite de max_tokens durante el uso de herramientas, vuelve a intentar la solicitud con un valor de max_tokens más alto.

Manejar el motivo de detención pause_turn

Al usar herramientas de servidor como la búsqueda web, la API puede devolver un motivo de detención pause_turn. Continúa la conversación devolviendo la respuesta pausada tal cual en una solicitud posterior.

Solución de errores

Error de ejecución de la herramienta

Si la propia herramienta genera un error durante la ejecución, devuelve el mensaje de error con "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Nombre de herramienta no válido

Si el intento de Claude de usar una herramienta no es válido (por ejemplo, faltan parámetros obligatorios), vuelve a intentar la solicitud con valores de description más detallados en tus definiciones de herramientas.

Mensajes en streaming

Al crear un Message, puedes establecer "stream": true para hacer “streaming” (transmisión incremental) de la respuesta usando “server-sent events” (eventos enviados por el servidor), o SSE.

Streaming con los SDK

import anthropic

client = anthropic.Anthropic()

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

Tipos de eventos

Cada evento enviado por el servidor incluye un tipo de evento con nombre y datos JSON asociados. Cada stream usa el siguiente flujo de eventos:

1. message_start: contiene un objeto Message con content vacío.
2. Una serie de bloques de contenido, cada uno con content_block_start, uno o más eventos content_block_delta y content_block_stop.
3. Uno o más eventos message_delta, que indican cambios de nivel superior en el objeto Message final.
4. Un evento message_stop final.

Advertencia: Los recuentos de tokens que se muestran en el campo usage del evento message_delta son acumulativos.

Tipos de delta de bloques de contenido

Delta de texto

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}

Delta de JSON de entrada

Para los bloques de contenido tool_use, los deltas son cadenas JSON parciales:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Delta de pensamiento

Al usar el pensamiento con streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}

Ejemplo básico de solicitud de streaming

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}