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), adopta la estructura propia de solicitudes y respuestas de Anthropic, permitiendo aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada de 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 las capacidades 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 como respaldo.

Si aún no ha iniciado sesión o no 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 finalizar, volverá automáticamente a la página actual.

Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluirá crédito gratuito para una experiencia sin costo; cuando el crédito sea insuficiente, puede recargar saldo universal 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. Necesitamos proporcionar al menos tres parámetros obligatorios:

• model: Selecciona el modelo Claude que se utilizará. claude-opus-5-5 solo se proporciona mediante Messages API, admite 1 millón de Token de contexto, una salida máxima de 128K Token y siempre habilita el pensamiento adaptativo. El último modelo insignia es claude-fable-5-1 (1 millón de Token de contexto, salida máxima de 128K Token); el anterior claude-fable-5 sigue siendo compatible y se conserva.
• messages: El arreglo de mensajes de entrada; cada mensaje contiene role (rol) y content (contenido), donde role admite user y assistant.
• max_tokens: El número máximo de tokens 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 generación, entre 0 y 1; cuanto mayor sea el valor, más divergente será la respuesta.
• stream: Indica si se utiliza una respuesta en streaming; establecerlo en true permite lograr un efecto de devolución carácter por carácter.
• stop_sequences: Secuencias de detención personalizadas; el modelo dejará de generar al encontrar estos textos.
• top_p: Parámetro de muestreo de núcleo, que controla la aleatoriedad de la generación junto con temperature.
• top_k: Solo realiza muestreo entre las K opciones con mayor probabilidad.
• tools: Definiciones de herramientas, utilizadas para permitir que el modelo invoque 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 un bloque de contenido específico.

​

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: Arreglo de contenido de 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 es la entrada no almacenada en caché; cache_creation_input_tokens y cache_read_input_tokens son respectivamente la escritura y lectura de caché; output_tokens es el número total de tokens 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 desglose puede ser null u omitirse cuando no haya un recuento autorizado.
• usage.cache_creation: Desglose 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 es igual a cache_creation_input_tokens; que el campo sea null u omitido indica que la respuesta actual no tiene un desglose de TTL disponible y no puede interpretarse como 0.
• usage.cost: Las respuestas no streaming pueden incluir un objeto de consumo de crédito 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 lo hubiera). 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 de$12.50 y $20/millón de Token, respectivamente; el precio real de la plataforma se convierte según el descuento del plan.

​

Prompt del sistema

Claude Messages API admite configurar el prompt 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 mensaje 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; basta con establecer el parámetro stream en true para obtener resultados devueltos progresivamente, lo que resulta 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, contiene 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, contiene el fragmento de texto recién generado.
• content_block_stop: finalización del bloque de contenido.
• message_delta: actualización incremental a nivel de mensaje, contiene stop_reason y la información final de usage. 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 resultado 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 observar, el evento content_block_delta de la respuesta en streaming contiene el contenido de texto generado progresivamente; al concatenar todos los text_delta se obtiene 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 todo 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 conversación en messages, Claude puede proporcionar respuestas precisas basadas en el contexto.

​

Modelo de razonamiento profundo

El thinking y el thinking summary de Claude son dos conceptos distintos: 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 el esfuerzo general 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 legible del razonamiento; no es la cadena de pensamiento original.
• display: "omitted" devuelve thinking: "", pero aún conserva la signature opaca para admitir conversaciones posteriores.
• El valor predeterminado de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 es omitted; Opus 4.6, Sonnet 4.6 y los modelos anteriores que admiten thinking usan summarized de forma predeterminada.
• Display solo afecta el contenido devuelto y la latencia de streaming, no desactiva el razonamiento ni reduce la facturación de los 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 el esfuerzo low / medium para controlar la inversión de razonamiento.
• Para los modelos que permiten desactivar thinking, se puede pasar thinking: {"type":"disabled"}; disabled solo puede combinarse con low, medium o high, xhigh / max devolverá 400.
• budget_tokens solo se usa para modelos antiguos que aún admiten presupuestos de pensamiento fijos. Los modelos nuevos deben usar thinking.type=adaptive y output_config.effort; thinking de Fable 5.1 siempre está activado y no puede desactivarse explícitamente.
• En conversaciones de varias rondas y llamadas a herramientas, se deben devolver sin cambios los bloques completos de thinking y signature devueltos por assistant; no modifique ni genere signature por su cuenta.
• Algunas rutas compatibles no pueden procesar sin pérdida redacted_thinking o la desactivación explícita de thinking; en ese caso devolverán un error de parámetros, en lugar de descartar silenciosamente o cambiar la semántica de 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 de visión

Claude admite entradas multimodales y puede procesar texto e imágenes al mismo tiempo. En la API de Messages, las capacidades de visión se pueden usar estableciendo content en formato de matriz y pasando bloques de contenido de imagen.

​

Usar 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())

​

Usar imágenes 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 compatibles incluyen: image/jpeg, image/png, image/gif, image/webp.

​

Documentos y PDF

Los PDF usan bloques de contenido document y admiten dos fuentes estables: Base64 y URL. Las fuentes Base64 deben usar 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 colocará 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 necesita controlar la posición con precisión, el mismo cache_control también puede escribirse en los bloques de contenido text, image, document, tool_use, tool_result o en las 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 escrituras de caché y no un desglose de TTL autorizado; en ese caso, no trate ningún bucket como un 0 conocido, y la facturación y el total siguen 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
  }
}

​

Uso 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 sus herramientas/funciones predefinidas cuando sea necesario.

​

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,
    "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 resultado devuelto incluirá un bloque de contenido de tipo tool_use en content:

{
  "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. Después de recibir este resultado, debe ejecutar la función de 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á la respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta.

​

Diferencias con la API de Chat Completion

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

El usage.input_tokens de la API de Mensajes solo representa la entrada no almacenada en caché; cache_read_input_tokens y cache_creation_input_tokens son grupos de facturación independientes; los tres se calcularán por separado según los precios correspondientes.

Característica	API de Mensajes (/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	Matriz content (admite varios tipos)	Matriz choices (incluye message)
Formato de 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 de compatibilidad
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 un cambio sin interrupciones. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar la API de Mensajes.

​

Manejo de errores

Las respuestas de error de las interfaces públicas 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 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; procese los errores 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 Mensajes de Claude para llamar a las funciones de conversación de Claude en el formato nativo de Anthropic. La API de Mensajes admite numerosas funciones, como conversación básica, mensajes del sistema, respuestas en streaming, conversación de múltiples turnos, razonamiento profundo, comprensión visual, PDF, caché de prompts y llamada de herramientas. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.