Solicitud y uso de Claude Messages API

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 y guárdelo para su uso posterior.

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.

📘 Documentación completa: Claude Messages API →

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

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

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:

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

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

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

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

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:

{
  "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:

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:

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

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

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

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:

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é:

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:

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

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:

{
  "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:

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

{
  "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.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Solicitud y uso de Claude Messages API

Proceso de solicitud

Uso básico

Ejemplo de cURL

Ejemplo de Python

Prompt del sistema

Ejemplo de Python

Respuesta en streaming

Ejemplo en Python

Ejemplo en JavaScript

Conversación de múltiples turnos

Ejemplo en Python

Modelo de razonamiento profundo

Modelos visuales

Uso de imágenes codificadas en Base64

Uso de imágenes mediante URL

Ejemplo de cURL

Documentos y PDF

Caché de prompts

Llamada de herramientas (Tool Use)

Ejemplo en Python

Diferencias con la API de Chat Completion

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Ejemplo de cURL

​Ejemplo de Python

​Prompt del sistema

​Ejemplo de Python

​Respuesta en streaming

​Ejemplo en Python

​Ejemplo en JavaScript

​Conversación de múltiples turnos

​Ejemplo en Python

​Modelo de razonamiento profundo

​Modelos visuales

​Uso de imágenes codificadas en Base64

​Uso de imágenes mediante URL

​Ejemplo de cURL

​Documentos y PDF

​Caché de prompts

​Llamada de herramientas (Tool Use)

​Ejemplo en Python

​Diferencias con la API de Chat Completion

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Ejemplo de cURL

Ejemplo de Python

Prompt del sistema

Ejemplo de Python

Respuesta en streaming

Ejemplo en Python

Ejemplo en JavaScript

Conversación de múltiples turnos

Ejemplo en Python

Modelo de razonamiento profundo

Modelos visuales

Uso de imágenes codificadas en Base64

Uso de imágenes mediante URL

Ejemplo de cURL

Documentos y PDF

Caché de prompts

Llamada de herramientas (Tool Use)

Ejemplo en Python

Diferencias con la API de Chat Completion

Manejo de errores

Ejemplo de respuesta de error

Conclusión