# Guía 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. Proporciona explicaciones y ejemplos de IDs de modelos/la API básica de mensajes, uso de herramientas, streaming, pensamiento extendido, y nada más.

---

# Guía 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. Proporciona explicaciones y ejemplos de IDs de modelos/la API básica de mensajes, uso de herramientas, streaming, pensamiento extendido, y nada más.

## Modelos

```text
Modelo más inteligente: Claude Opus 4.6: claude-opus-4-6
Modelo inteligente: Claude Sonnet 4.6: claude-sonnet-4-6
Para tareas rápidas y rentables: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Llamando a la API

### Solicitud y respuesta básica

<CodeGroup>

```bash CLI
ant messages create \
  --model claude-opus-4-6 \
  --max-tokens 1024 \
  --message '{"role": "user", "content": "Hello, Claude"}'
```

```python Python
import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
```

</CodeGroup>

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

### Múltiples turnos conversacionales

La API de mensajes no tiene estado, lo que significa que siempre envías el historial conversacional completo a la API. Puedes usar este patrón para construir una conversación a lo largo del tiempo. Los turnos conversacionales anteriores no necesariamente tienen que originarse de Claude. Puedes usar mensajes `assistant` sintéticos.

<CodeGroup>

```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 1024
messages:
  - role: user
    content: Hello, Claude
  - role: assistant
    content: Hello!
  - role: user
    content: Can you describe LLMs to me?
YAML
```

```python Python
import anthropic

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

</CodeGroup>

### Poniendo palabras en la boca de Claude

Puedes pre-rellenar parte de la respuesta de Claude en la última posición de la lista de mensajes de entrada. Esto puede usarse para dar forma a la respuesta de Claude. El ejemplo a continuación usa `"max_tokens": 1` para obtener una única respuesta de opción múltiple de Claude.

<CodeGroup>

```bash CLI
ant messages create <<'YAML'
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 ("
YAML
```

```python Python
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 ("},
    ],
)
```

</CodeGroup>

### Visión

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

<CodeGroup>

```bash CLI nocheck
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7"
IMAGE_URL="$IMAGE_URL/Camponotus_flavomarginatus_ant.jpg"

# Opción 1: Imagen codificada en Base64 (el prefijo @ auto-codifica archivos binarios como base64)
curl -sSo ant.jpg "$IMAGE_URL"

ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 1024
messages:
  - role: user
    content:
      - type: image
        source:
          type: base64
          media_type: image/jpeg
          data: "@./ant.jpg"
      - type: text
        text: What is in the above image?
YAML

# Opción 2: Imagen referenciada por URL
ant messages create <<YAML
model: claude-opus-4-6
max_tokens: 1024
messages:
  - role: user
    content:
      - type: image
        source:
          type: url
          url: $IMAGE_URL
      - type: text
        text: What is in the above image?
YAML
```

```python Python nocheck
import anthropic
import base64
import httpx

# Opción 1: Imagen codificada en Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    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?"},
            ],
        }
    ],
)

# Opción 2: Imagen referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
```

</CodeGroup>

## Pensamiento extendido

El pensamiento extendido a veces puede ayudar a Claude con tareas muy difíciles. Cuando está habilitado, la temperatura debe establecerse en 1.

El pensamiento extendido es compatible con los siguientes modelos:

- Claude Opus 4.1 (`claude-opus-4-1-20250805`)
- Claude Opus 4 (`claude-opus-4-20250514`)
- Claude Sonnet 4.6 (`claude-sonnet-4-6`)
- Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)

### Cómo funciona el pensamiento extendido

Cuando el pensamiento extendido está activado, Claude crea bloques de contenido `thinking` donde genera su razonamiento interno. La respuesta de la API incluirá bloques de contenido `thinking`, seguidos de bloques de contenido `text`.

<CodeGroup>

```bash CLI
ant messages create \
  --transform content --format yaml <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
messages:
  - role: user
    content: Are there an infinite number of prime numbers such that n mod 4 == 3?
YAML
```

```python Python
import anthropic

client = anthropic.Anthropic()

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

# La respuesta contendrá bloques de pensamiento resumidos y bloques de texto
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")
```

</CodeGroup>

El parámetro `budget_tokens` determina el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno. En los modelos Claude 4, este límite se aplica a los tokens de pensamiento completos, y no a la salida resumida. Presupuestos más grandes pueden mejorar la calidad de la respuesta al permitir un análisis más exhaustivo para problemas complejos. Una regla: el valor de max_tokens debe ser estrictamente mayor que el valor de budget_tokens para que Claude tenga espacio para escribir su respuesta después de que el pensamiento esté completo.

## Pensamiento extendido con uso de herramientas

El pensamiento extendido puede usarse junto con el uso de herramientas, permitiendo que Claude razone a través de la selección de herramientas y el procesamiento de resultados.

Limitaciones importantes:

1. **Limitación de elección de herramienta:** Solo admite `tool_choice: {"type": "auto"}` (predeterminado) o `tool_choice: {"type": "none"}`.
2. **Preservar bloques de pensamiento:** Durante el uso de herramientas, debes pasar los bloques `thinking` de vuelta a la API para el último mensaje del asistente.

### Preservando bloques de pensamiento

<CodeGroup>

```bash CLI nocheck
# Primera solicitud: captura el array de contenido del asistente (bloques thinking + tool_use,
# firmas intactas) como JSON compacto.
ASSISTANT_CONTENT=$(ant messages create \
  --transform content --format jsonl <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
tools:
  - 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]
messages:
  - role: user
    content: "What's the weather in Paris?"
YAML
)

TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT" \
  | grep -o 'toolu_[A-Za-z0-9]*')

# Segunda solicitud: pasa los bloques capturados de vuelta sin cambios como el mensaje
# del asistente. El bloque thinking debe acompañar al bloque tool_use.
ant messages create <<YAML
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
tools:
  - 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]
messages:
  - role: user
    content: "What's the weather in Paris?"
  - role: assistant
    content: $ASSISTANT_CONTENT
  - role: user
    content:
      - type: tool_result
        tool_use_id: $TOOL_USE_ID
        content: "Current temperature: 72°F"
YAML
```

```python Python nocheck
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 solicitud de herramienta
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extraer el bloque de pensamiento y el bloque de uso de herramienta
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 - Incluir el bloque de pensamiento y el resultado de la herramienta
continuation = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Nota: el thinking_block se pasa junto con el 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",
                }
            ],
        },
    ],
)
```

</CodeGroup>

### Pensamiento intercalado

El pensamiento extendido con uso de herramientas en los modelos Claude 4 admite el pensamiento intercalado, que permite a Claude pensar entre llamadas a herramientas. Para habilitarlo en los modelos Claude 4, 4.5 y Sonnet 4.6, agrega el encabezado beta `interleaved-thinking-2025-05-14` a tu solicitud de API.

<CodeGroup>

```bash CLI nocheck
ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML'
model: claude-sonnet-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
tools:
  - name: calculator
    description: Perform arithmetic calculations.
    input_schema:
      type: object
      properties:
        expression:
          type: string
          description: The math expression to evaluate.
      required:
        - expression
  - name: database_query
    description: Query the product database.
    input_schema:
      type: object
      properties:
        query:
          type: string
          description: The database query.
      required:
        - query
messages:
  - role: user
    content: "What's the total revenue if we sold 150 units of product A at $50 each?"
YAML
```

```python Python nocheck
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"],
)
```

</CodeGroup>

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

<Info>
  Para Claude Opus 4.6, el pensamiento intercalado se habilita automáticamente cuando se usa el [pensamiento adaptativo](/docs/es/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`). No se necesita encabezado beta. Sonnet 4.6 admite tanto el encabezado beta `interleaved-thinking-2025-05-14` con pensamiento extendido manual como el pensamiento adaptativo.
</Info>

## Uso de herramientas

### Especificando herramientas del cliente

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

| Parámetro      | Descripción                                                                                                                  |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| `name`         | El nombre de la herramienta. Debe coincidir con la expresión regular `^[a-zA-Z0-9_-]{1,64}$`.                                |
| `description`  | Una descripción detallada en texto plano de lo que hace la herramienta, cuándo debe usarse y cómo se comporta.               |
| `input_schema` | Un objeto [JSON Schema](https://json-schema.org/) que define los parámetros esperados para la herramienta.                   |

```json
{
  "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 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 sobre la herramienta, incluyendo:

- Qué hace la herramienta
- Cuándo debe usarse (y cuándo no)
- Qué significa cada parámetro y cómo afecta el 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 ayuda a Claude a entender los patrones de entrada esperados. Consulta [Proporcionando ejemplos de uso de herramientas](/docs/es/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) para más detalles.

Ejemplo de una buena descripción de herramienta:

```json
{
  "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"]
  }
}
```

## Controlando la salida de Claude

### Forzando el uso de herramientas

Puedes forzar a Claude a usar una herramienta específica especificando la herramienta en el campo `tool_choice`:

```python
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 a alguna de las herramientas proporcionadas o no (predeterminado).
- `any` le dice a Claude que debe usar una de las herramientas proporcionadas.
- `tool` obliga a Claude a usar siempre una herramienta particular.
- `none` evita que Claude use cualquier herramienta.

### Salida JSON

Las herramientas no necesariamente tienen que ser funciones del cliente. Puedes usar herramientas en cualquier momento que quieras que el modelo devuelva salida JSON que siga un esquema proporcionado.

### Cadena de pensamiento

Al usar herramientas, Claude a menudo mostrará su "cadena de pensamiento", es decir, el razonamiento paso a paso que usa para desglosar el problema y decidir qué herramientas usar.

```json
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}
```

### Uso paralelo de herramientas

Por defecto, Claude puede usar múltiples herramientas para responder una consulta del usuario. Puedes deshabilitar este comportamiento configurando `disable_parallel_tool_use=true`.

## Manejo de bloques de contenido de uso de herramientas y resultados de herramientas

### Manejo de resultados de herramientas del cliente

La respuesta tendrá 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 herramienta 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.

Cuando recibes una respuesta de uso de herramienta, debes:

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

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

### Manejo de la razón de parada `max_tokens`

Si la respuesta de Claude se corta debido a alcanzar el límite de `max_tokens` durante el uso de herramientas, reintenta la solicitud con un valor de `max_tokens` más alto.

### Manejo de la razón de parada `pause_turn`

Al usar herramientas del servidor como la búsqueda web, la API puede devolver una razón de parada `pause_turn`. Continúa la conversación pasando la respuesta pausada tal como está en una solicitud posterior.

## Solución de errores

### Error de ejecución de herramienta

Si la herramienta en sí arroja un error durante la ejecución, devuelve el mensaje de error con `"is_error": true`:

```json
{
  "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 inválido

Si el intento de uso de una herramienta por parte de Claude es inválido (por ejemplo, faltan parámetros requeridos), intenta la solicitud nuevamente con valores de `description` más detallados en tus definiciones de herramientas.

## Mensajes en streaming

Al crear un mensaje, puedes establecer `"stream": true` para transmitir incrementalmente la respuesta usando eventos enviados por el servidor (SSE).

### Streaming con SDKs

<CodeGroup>

```bash CLI
ant messages create --stream --format jsonl \
  --model claude-opus-4-6 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello"}' \
  | while IFS= read -r event; do
      [[ $event == *'"text_delta"'* ]] || continue
      text=${event#*'"text":"'}
      printf '%b' "${text%\"*}"
    done
```

```python Python
import anthropic

client = anthropic.Anthropic()

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

</CodeGroup>

### Tipos de eventos

Cada evento enviado por el servidor incluye un tipo de evento nombrado 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 al objeto `Message` final.
4. Un evento final `message_stop`.

**Advertencia:** Los recuentos de tokens mostrados en el campo `usage` del evento `message_delta` son _acumulativos_.

### Tipos de delta de bloque de contenido

#### Delta de texto

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

#### Delta de JSON de entrada

Para bloques de contenido `tool_use`, los deltas son _cadenas JSON parciales_:

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

#### Delta de pensamiento

Al usar pensamiento extendido con streaming:

```json
{
  "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

```sse
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-6", "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"}
```