> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Solicitud y uso de Claude Messages API

> Claude AI API guide - Ace Data Cloud

Anthropic Claude es un sistema de conversación de IA muy potente; basta con introducir un prompt para generar respuestas fluidas y naturales en apenas unos segundos. Claude Messages API es el formato de API nativo oficial de Anthropic. A diferencia del formato compatible con OpenAI (Chat Completion), utiliza la propia estructura de solicitudes y respuestas de Anthropic, lo que permite aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada a herramientas, el pensamiento profundo (Extended Thinking) y otras características avanzadas.

Este documento presenta principalmente el proceso de uso de las operaciones de Claude Messages API. Con ella, podemos utilizar una interfaz nativa coherente con la oficial de Anthropic para invocar la función de conversación de Claude.

## Proceso de solicitud

Para utilizar Claude Messages API, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo para su uso posterior.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Si aún no ha iniciado sesión o se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, regresará automáticamente a la página actual.

**Un API Token permite invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye saldo gratuito, que permite una experiencia sin costo; cuando el saldo sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages)

## Uso básico

La ruta de solicitud de Claude Messages API es `/v1/messages`, coherente con la API oficial de Anthropic. Como mínimo, debemos proporcionar tres parámetros obligatorios:

* `model`: seleccione el modelo Claude que desea utilizar. `claude-opus-5-5` solo se proporciona mediante Messages API, admite un contexto de 1 millón de Token, una salida máxima de 128K Token y siempre habilita el pensamiento adaptativo. El buque insignia más reciente es `claude-fable-5-1` (contexto de 1 millón de Token, salida máxima de 128K Token); el anterior `claude-fable-5` sigue conservándose por compatibilidad. `claude-sonnet-5-5` se ha incorporado a la interfaz de la serie nativa Messages, admite entrada de imágenes y pensamiento adaptativo; sus precios de referencia oficiales de entrada, salida y lectura de caché son respectivamente 2, 10 y 0.20 dólares por millón de Token.
* `messages`: matriz de mensajes de entrada, donde cada mensaje incluye `role` (rol) y `content` (contenido), y `role` admite `user` y `assistant`.
* `max_tokens`: número máximo de token de salida, utilizado para limitar la longitud de una sola respuesta.

Parámetros opcionales comunes:

* `system`: prompt del sistema, utilizado para establecer el comportamiento y el rol del modelo.
* `temperature`: aleatoriedad de la generación, entre 0 y 1; cuanto mayor sea el valor, más dispersa será la respuesta.
* `stream`: si se utiliza respuesta en streaming; establecerlo en `true` permite lograr un efecto de devolución palabra por palabra.
* `stop_sequences`: secuencias de detención personalizadas; el modelo dejará de generar cuando encuentre estos textos.
* `top_p`: parámetro de muestreo de núcleo, que controla la aleatoriedad de la generación junto con temperature.
* `top_k`: realiza el muestreo solo entre las K opciones con mayor probabilidad.
* `tools`: definición de herramientas, utilizada para permitir que el modelo llame a funciones externas.
* `tool_choice`: controla cómo utiliza el modelo las herramientas proporcionadas.
* `cache_control`: crea automáticamente un punto de interrupción de caché en el último bloque de contenido almacenable en caché de la solicitud; también puede escribirse en bloques de contenido específicos.

### Ejemplo de cURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'
```

### Ejemplo de Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Después de la llamada, el resultado devuelto es el siguiente:

```json theme={null}
{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}
```

Descripción de los campos del resultado devuelto:

* `id`: identificador único de este mensaje.
* `type`: siempre es `message`.
* `role`: siempre es `assistant`.
* `content`: matriz de contenido de la respuesta; cada elemento contiene `type` (como `text`) y el contenido correspondiente.
* `model`: nombre del modelo que procesa la solicitud.
* `stop_reason`: motivo de detención. Los valores estables incluyen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puede devolver el contenido actual de assistant sin cambios para continuar), `refusal` y `model_context_window_exceeded`.
* `stop_sequence`: si se detiene debido a una secuencia de detención personalizada, muestra el texto de la secuencia de detención coincidente.
* `stop_details`: cuando `stop_reason` es `refusal`, puede incluir la categoría y la explicación del rechazo.
* `usage`: estadísticas de uso de token. `input_tokens` corresponde a la entrada no almacenada en caché; `cache_creation_input_tokens` y `cache_read_input_tokens` corresponden respectivamente a la escritura y lectura de caché; `output_tokens` es el número total de token de salida. Si se devuelve `output_tokens_details.thinking_tokens`, este valor es un subconjunto de `output_tokens`; no lo sume de nuevo al calcular el total o el costo. Este detalle puede ser `null` u omitirse cuando no haya un recuento autorizado.
* `usage.cache_creation`: detalle opcional de TTL de escritura de caché, que incluye `ephemeral_5m_input_tokens` y `ephemeral_1h_input_tokens`. Cuando el objeto existe, la suma de ambos equivale a `cache_creation_input_tokens`; que el campo sea `null` o se omita indica que la respuesta actual no tiene un desglose de TTL disponible y no debe interpretarse como `0`.
* `usage.cost`: las respuestas sin streaming pueden incluir un objeto de consumo de saldo registrado por Ace Data Cloud, donde `amount` es el consumo real de esta solicitud, `currency` es la unidad de medida y `list_amount` es el importe antes del descuento (si existe). El precio base oficial de lectura de caché de Fable 5.1 es de $0.25/millón de Token, y los precios base de escritura de caché de 5 minutos y 1 hora son respectivamente $12.50 y \$20/millón de Token; el precio real de la plataforma se calcula según el descuento del plan.

## Prompt del sistema

Claude Messages API admite establecer prompts del sistema mediante el campo `system`, utilizado para definir el comportamiento, el rol y el contexto del modelo.

### Ejemplo de Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Al configurar el prompt de `system`, se puede controlar con precisión el rol y el comportamiento de Claude.

## Respuesta en streaming

Esta interfaz también admite respuestas en streaming; establezca el parámetro `stream` en `true` para obtener un efecto de retorno gradual, lo cual es muy adecuado para implementar una visualización carácter por carácter en páginas web.

### Ejemplo en Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
```

La respuesta en streaming se devuelve en formato Server-Sent Events (SSE), y cada línea tiene los prefijos `event:` y `data:`. Los tipos de eventos de streaming incluyen:

* `message_start`: inicio del mensaje, incluye la información básica del mensaje y el nombre del modelo.
* `content_block_start`: inicio del bloque de contenido.
* `content_block_delta`: actualización incremental del bloque de contenido, incluye los fragmentos de texto recién generados.
* `content_block_stop`: finalización del bloque de contenido.
* `message_delta`: actualización incremental a nivel de mensaje, incluye la información de `stop_reason` y `usage` final. El valor autorizado de `output_tokens_details.thinking_tokens` solo debe leerse del último `message_delta.usage`; no se debe acumular entre eventos.
* `message_stop`: finalización del mensaje.

El efecto de salida es el siguiente:

```
event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

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":"Hi"}}

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

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"}
```

Como se puede ver, el evento `content_block_delta` de la respuesta en streaming contiene el contenido de texto generado gradualmente; al concatenar todos los `text_delta` se puede obtener la respuesta completa.

### Ejemplo en JavaScript

```javascript theme={null}
const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hello, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}
```

## Conversación de múltiples turnos

Si desea integrar la función de conversación de múltiples turnos, debe alternar los mensajes con los roles `user` y `assistant` en el arreglo `messages`, y pasar también el historial de conversación anterior.

### Ejemplo en Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

El resultado devuelto es el siguiente:

```json theme={null}
{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}
```

Al pasar el historial completo de la conversación en `messages`, Claude puede proporcionar respuestas precisas en función del contexto.

## Modelo de razonamiento profundo

El thinking y el thinking summary de Claude son dos conceptos diferentes: el modelo puede realizar razonamiento interno, pero la API no devuelve la cadena de pensamiento original. Cuando se necesita mostrar el proceso de razonamiento, la API devuelve un resumen procesado.

Actualmente, se recomienda utilizar adaptive thinking con el modelo actual y controlar la inversión total de razonamiento mediante `output_config.effort`:

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

El bloque thinking de la respuesta tiene la siguiente forma:

```json theme={null}
{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}
```

* `display: "summarized"` devuelve un resumen de pensamiento legible; no es la cadena de pensamiento original.
* `display: "omitted"` devuelve `thinking: ""`, pero aún conserva una `signature` opaca para admitir conversaciones posteriores.
* `display: "updates"` es el modo beta de Anthropic y requiere incluir `anthropic-beta: thinking-display-updates-2026-08-18`. La definición oficial es ocultar el cuerpo del razonamiento y mostrar actualizaciones breves de progreso entre llamadas a herramientas. La plataforma transmite este parámetro y el encabezado de solicitud beta según sus valores originales, y no lo reescribe forzosamente como `summarized`; el contenido de salida real depende de la compatibilidad del modelo seleccionado.
* `thinking`, `output_config`, effort, parámetros de muestreo y campos de extensión añadidos se transmiten según sus valores originales. La plataforma no mantiene enumeraciones de valores ni restricciones de combinación codificadas de forma fija por modelo, ni reescribe automáticamente los modos de thinking; el modelo seleccionado determina si acepta estos parámetros, y los errores de parámetros devueltos por el modelo se transmiten al cliente.
* Los valores predeterminados de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 son `omitted`; Opus 4.6, Sonnet 4.6 y los modelos anteriores compatibles con thinking usan `summarized` de forma predeterminada.
* Display solo afecta al contenido devuelto y a la latencia de streaming; no desactiva el razonamiento ni reduce la facturación de tokens de thinking.
* Si thinking está habilitado de forma predeterminada y el valor predeterminado de display son dos cuestiones independientes. Opus 5 y Sonnet 5 habilitan adaptive thinking de forma predeterminada; para Opus 5, omitir `thinking` equivale a adaptive, y omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 y 4.6 requieren habilitación explícita.
* Thinking y el cuerpo final comparten el presupuesto de salida de `max_tokens`. Cuando el presupuesto es demasiado pequeño, thinking puede consumir la mayor parte de la cuota, dejando el cuerpo vacío o truncado; aumente `max_tokens` o use effort `low` / `medium` para controlar la inversión de razonamiento.
* Para los modelos que permiten desactivar thinking, se puede pasar `thinking: {"type":"disabled"}`. Los nuevos modos como `between_tools` y las combinaciones de effort dependen del modelo seleccionado; la plataforma no los rechaza por adelantado basándose en reglas de modelos antiguas.
* El presupuesto de pensamiento fijo se puede transmitir mediante `budget_tokens`; los modelos nuevos suelen utilizar `thinking.type=adaptive` y `output_config.effort`. Si se admite un presupuesto fijo o la desactivación del pensamiento depende de las capacidades actuales del modelo seleccionado.
* En conversaciones de múltiples turnos y llamadas a herramientas, se deben devolver sin modificaciones los bloques completos de thinking y signature devueltos por el assistant; no modifique ni genere signatures por su cuenta.
* La transmisión de parámetros no significa que cada modelo admita todas las funciones. Las llamadas entre protocolos aún requieren conversión, y el alcance de compatibilidad y los errores de contenidos como `redacted_thinking` son determinados por el servicio de modelo que procesa realmente la solicitud.

En las solicitudes de streaming, `summarized` produce `thinking_delta`; `omitted` no produce `thinking_delta`, solo conserva el ciclo de vida del bloque thinking y `signature_delta`.

## Modelos visuales

Claude admite entradas multimodales y puede procesar texto e imágenes simultáneamente. En la API de Messages, las capacidades visuales se pueden utilizar estableciendo `content` en formato de matriz y pasando bloques de contenido de imagen.

### Uso de imágenes codificadas en Base64

```python theme={null}
import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# 读取并编码图片
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Uso de imágenes mediante URL

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Ejemplo de cURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'
```

Los formatos de imagen admitidos incluyen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.

## Documentos y PDF

Los PDF utilizan el bloque de contenido `document` y admiten dos fuentes estables: Base64 y URL. Las fuentes Base64 deben utilizar `application/pdf`:

```python theme={null}
import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}
```

La fuente URL se escribe como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` también admite `text/plain` y fuentes `content` compuestas por bloques text/image; los campos opcionales incluyen `title`, `context` y `citations`. La fuente `file_id` de la API de Files pertenece a una función beta independiente y no forma parte del contrato estable de esta interfaz.

## Caché de prompts

`cache_control` de nivel superior coloca automáticamente el punto de interrupción de caché en el último bloque almacenable en caché:

```python theme={null}
payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}
```

Cuando se requiera un control preciso de la posición, también puede escribir el mismo `cache_control` en bloques de contenido text, image, document, tool\_use, tool\_result o en definiciones de herramientas. `ttl` admite `5m` (predeterminado) y `1h`; determine la escritura y los aciertos de caché mediante `usage.cache_creation_input_tokens` y `usage.cache_read_input_tokens`.

Cuando la respuesta proporciona `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` es `null` o se omite, indica que solo existe el total de escritura de caché y no hay un desglose de TTL autoritativo; en este caso, no considere ningún bucket como un 0 conocido, y la facturación y el total seguirán basándose en el campo agregado.

Ejemplo de resultado devuelto:

```json theme={null}
{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}
```

## Llamada de herramientas (Tool Use)

La API de Mensajes de Claude admite de forma nativa la funcionalidad de llamada de herramientas, lo que permite al modelo llamar a las herramientas/funciones que usted haya predefinido cuando sea necesario.

### Ejemplo en Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "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"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Cuando el modelo decide llamar a una herramienta, el `content` del resultado devuelto incluirá un bloque de contenido de tipo `tool_use`:

```json theme={null}
{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}
```

Tenga en cuenta que `stop_reason` es `tool_use`, lo que indica que el modelo necesita llamar a una herramienta. Tras recibir este resultado, debe ejecutar la función de la herramienta y devolver el resultado al modelo en forma de `tool_result`:

```python theme={null}
payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "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"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

El modelo generará una respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta.

## Diferencias con la API de Chat Completion

Ace Data Cloud ofrece simultáneamente dos formatos de API de Claude; las principales diferencias entre ambos son las siguientes:

El `usage.input_tokens` de la API de Messages solo representa entradas sin caché; `cache_read_input_tokens` y `cache_creation_input_tokens` son buckets de facturación independientes; los tres se calculan por separado según los precios correspondientes.

| Característica | API de Messages (`/v1/messages`) | API de Chat Completion (`/v1/chat/completions`) |
| - | - | - |
| Formato | Formato nativo de Anthropic | Formato compatible con OpenAI |
| Mensaje del sistema | Campo `system` independiente | Se transmite mediante `role: "system"` en `messages` |
| Estructura de respuesta | Array `content` (admite varios tipos) | Array `choices` (incluye `message`) |
| Transmisión en streaming | Eventos SSE (varios tipos de eventos) | Líneas SSE `data` |
| Razonamiento profundo | `thinking` nativo y `output_config.effort` | Estrategia predeterminada del modelo y parámetros compatibles |
| Llamada de herramientas | `tools` + `input_schema` nativos | Formato `tools` compatible con OpenAI |
| Estadísticas de tokens | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` |

Si su sistema ya está integrado con una API en formato OpenAI, puede utilizar la API de Chat Completion para realizar una transición fluida. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar la API de Messages.

## Manejo de errores

Las respuestas de error de la interfaz pública utilizan el envelope de la plataforma Ace Data Cloud: `error.code` es un código de error estable, `error.message` es una descripción y `trace_id` se utiliza para investigar solicitudes. Los estados HTTP comunes incluyen:

* `400`: Los parámetros de la solicitud o el contenido del protocolo no son válidos.
* `401`: El token de autorización no es válido, falta o ha expirado.
* `403`: Acceso prohibido, saldo insuficiente o cuota restringida.
* `404`: La API o el modelo no existe.
* `413`: El cuerpo de la solicitud es demasiado grande.
* `429`: Demasiadas solicitudes.
* `500` / `503` / `504`: Error del servicio, no disponible temporalmente o tiempo de espera de procesamiento agotado.

### Ejemplo de respuesta de error

```json theme={null}
{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Esta estructura de error es el contrato de tiempo de ejecución de Ace Data Cloud y no equivale al envelope de error oficial de Anthropic; procéselo según el estado HTTP y `error.code`.

## Conclusión

A través de este documento, ya ha aprendido cómo utilizar la API de Messages de Claude para invocar la funcionalidad de conversación de Claude en el formato nativo de Anthropic. La API de Messages admite funciones enriquecidas como conversación básica, mensajes de sistema, respuestas en streaming, conversaciones de múltiples turnos, razonamiento profundo, comprensión visual, PDF, caché de prompts y llamadas a herramientas. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.