Solicitud y uso de la API de Claude Messages

Anthropic Claude es un sistema de conversación AI muy potente, que puede generar respuestas fluidas y naturales en cuestión de segundos simplemente ingresando un mensaje. La API de Claude Messages es el formato nativo oficial de Anthropic, que, a diferencia del formato compatible con OpenAI (Chat Completion), utiliza su propia estructura de solicitud y respuesta, 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 describe principalmente el proceso de uso de la API de Claude Messages, que nos permite utilizar una interfaz nativa consistente con la oficial de Anthropic para invocar las funciones de conversación de Claude.

Proceso de solicitud

Para usar la API de Claude Messages, primero puedes ir a la página de Claude Messages API y hacer clic en el botón “Acquire” para obtener las credenciales necesarias para la solicitud:

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invita a registrarte e iniciar sesión. Después de registrarte e iniciar sesión, serás redirigido automáticamente a la página actual. En la primera solicitud, se otorgará un crédito gratuito, lo que te permitirá usar esta API de forma gratuita.

Uso básico

La ruta de solicitud de la API de Claude Messages es /v1/messages, manteniendo la consistencia con la API oficial de Anthropic. Necesitamos proporcionar al menos tres parámetros obligatorios:

model: seleccionar el modelo de Claude a utilizar, como claude-opus-4-20250514, claude-sonnet-4-20250514, etc.
messages: un array de mensajes de entrada, donde cada mensaje contiene role (rol) y content (contenido), siendo role compatible con user y assistant.
max_tokens: número máximo de tokens de salida, utilizado para limitar la longitud de la respuesta única.

Parámetros opcionales comunes:

system: mensaje del sistema, utilizado para establecer el comportamiento y rol del modelo.
temperature: aleatoriedad de la generación, entre 0 y 1, donde un valor mayor produce respuestas más dispersas.
stream: si se utiliza respuesta en streaming, configurado como true para lograr un efecto de retorno palabra por palabra.
stop_sequences: secuencias de parada personalizadas, el modelo dejará de generar al encontrar estos textos.
top_p: parámetro de muestreo nuclear, que junto con la temperatura controla la aleatoriedad de la generación.
top_k: muestreo solo de las K opciones con mayor probabilidad.
tools: definición de herramientas, para permitir que el modelo llame a funciones externas.
tool_choice: controla cómo el modelo utiliza las herramientas proporcionadas.

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": "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-sonnet-4-20250514",
    "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": "¡Hola! Mi nombre es Claude. ¿Cómo puedo ayudarte hoy?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "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 del mensaje actual.
type: siempre es message.
role: siempre es assistant.
content: array de contenido de respuesta, donde cada elemento contiene type (como text) y el contenido correspondiente.
model: nombre del modelo que procesó la solicitud.
stop_reason: razón de la detención, los valores posibles incluyen end_turn (fin normal), max_tokens (alcanzó la longitud máxima), stop_sequence (encontró una secuencia de parada), tool_use (llamada a herramientas).
stop_sequence: si se detuvo debido a una secuencia de parada personalizada, muestra el texto de la secuencia de parada coincidente.
usage: estadísticas de uso de tokens, que incluyen input_tokens (número de tokens de entrada) y output_tokens (número de tokens de salida).

Mensaje del sistema

La API de Claude Messages admite la configuración de mensajes del sistema a través del campo system, utilizado para definir el comportamiento, rol y 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": "Eres un asistente de traducción profesional en chino, por favor traduce el inglés ingresado por el usuario al chino.",
    "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 establecer el mensaje 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, configurando el parámetro stream como true para obtener un efecto de retorno paso a paso, ideal para implementar una visualización palabra por palabra en una página web.

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,
    "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 de Server-Sent Events (SSE), donde cada línea tiene como prefijo event: y data:. Los tipos de eventos en streaming incluyen:

message_start: inicio del mensaje, que 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, que incluye nuevos fragmentos de texto generados.
content_block_stop: fin del bloque de contenido.
message_delta: actualización incremental a nivel de mensaje, que incluye stop_reason y la información final de usage.
message_stop: fin 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":"Hola"}}

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. ¿Cómo puedo ayudarte hoy?"}}

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

Se puede ver que la respuesta en streaming contiene eventos content_block_delta que incluyen el contenido de texto generado paso a paso, y al concatenar todos los text_delta se puede obtener la respuesta completa.

Ejemplo de 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: "Hola, 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));
}

Diálogo de múltiples turnos

Si deseas integrar la función de diálogo de múltiples turnos, necesitas alternar los mensajes de los roles user y assistant en el array messages, incluyendo el historial de conversación anterior.

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,
    "messages": [
        {"role": "user", "content": "Hola, mi nombre es Alice."},
        {"role": "assistant", "content": "¡Hola Alice! Encantado de conocerte. ¿Cómo puedo ayudarte hoy?"},
        {"role": "user", "content": "¿Cuál es mi nombre?"}
    ]
}

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": "Tu nombre es Alice, ¡como acabas de decirme!"
    }
  ],
  "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 teniendo en cuenta el contexto.

Modelo de pensamiento profundo

Claude admite la función de Pensamiento Extendido, que permite al modelo realizar razonamientos internos antes de responder, mejorando la precisión en el manejo de problemas complejos. Para usar esta función, se debe pasar el parámetro thinking.

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": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "¿Cuál es el seno de 30 grados? Muestra tu razonamiento."}
    ]
}

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

El resultado devuelto es el siguiente:

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "El usuario está preguntando por el seno de 30 grados. Esta es una pregunta básica de trigonometría.\n\nEn un triángulo 30-60-90, los lados están en la proporción 1:√3:2.\n\nPara un ángulo de 30°:\n- El lado opuesto es 1\n- La hipotenusa es 2\n- Así que sin(30°) = opuesto/hipotenusa = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "El seno de 30 grados es **1/2** o **0.5**.\n\nEste es uno de los valores trigonométricos fundamentales. En un triángulo 30-60-90, los lados están en la proporción 1:√3:2, donde el lado opuesto al ángulo de 30° tiene longitud 1 y la hipotenusa tiene longitud 2, dándonos sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

Se puede ver que el array content contiene dos bloques de contenido:

type: "thinking": el proceso de pensamiento interno del modelo, mostrando los pasos de razonamiento.
type: "text": el resultado final de la respuesta.

Consideraciones:

Al usar thinking, max_tokens debe ser mayor que budget_tokens, ya que budget_tokens es el presupuesto de tokens asignado para el proceso de pensamiento.
Cuanto mayor sea budget_tokens, mayor será el espacio para que el modelo realice un razonamiento más profundo, adecuado para manejar problemas complejos.

Modelo visual

Claude admite entradas multimodales, pudiendo procesar texto e imágenes simultáneamente. En la API de Messages, se puede utilizar la capacidad visual configurando content como un formato de array e incluyendo bloques de contenido de imagen.

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

# Leer y codificar la imagen
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": "¿Qué hay en esta imagen?"
                }
            ]
        }
    ]
}

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

Usando imágenes de 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",
                        "media_type": "image/png",
                        "data": "https://example.com/image.png"
                    }
                },
                {
                    "type": "text",
                    "text": "¿Qué hay en esta imagen?"
                }
            ]
        }
    ]
}

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

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": "¿Qué hay en esta imagen?"
                }
            ]
        }
    ]
}

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

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": "¿Qué hay en esta imagen?"
          }
        ]
      }
    ]
  }'

Los formatos de imagen compatibles incluyen: image/jpeg, image/png, image/gif, image/webp. Ejemplo de resultado de retorno:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Esta imagen muestra una interfaz de configuración de solicitud de API para lo que parece ser un servicio de finalización de chat de IA. La interfaz incluye parámetros para la selección de modelo, mensajes, modo de transmisión y configuraciones de tokens máximos."
    }
  ],
  "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 función de llamada a herramientas, lo que permite al modelo invocar 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": "Obtener el clima actual en una ubicación dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "¿Cómo está el clima en 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:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Déjame verificar el clima en San Francisco para ti."
    },
    {
      "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
  }
}

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtener el clima actual en una ubicación dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "¿Cómo está el clima en San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Déjame verificar el clima en San Francisco para ti."},
                {"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": "Soleado, 72°F"
                }
            ]
        }
    ]
}

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

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

Diferencias con la API de Chat Completion

Ace Data Cloud ofrece dos formatos de API de Claude, y las principales diferencias son las siguientes:

Característica	API de Mensajes (`/v1/messages`)	API de Chat Completion (`/v1/chat/completions`)
Formato	Formato nativo de Anthropic	Formato compatible con OpenAI
Prompt del sistema	Campo `system` independiente	Se pasa a través de `messages` en `role: "system"`
Estructura de respuesta	Array `content` (admite múltiples tipos)	Array `choices` (contiene `message`)
Formato de flujo	Eventos SSE (múltiples tipos de eventos)	Línea SSE `data`
Pensamiento profundo	Parámetro `thinking` nativo	Se activa mediante un nombre de modelo especial (como sufijo `-thinking`)
Llamada a herramientas	`tools` nativo + `input_schema`	Formato `functions` compatible con OpenAI
Estadísticas de tokens	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

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

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:

400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
401 invalid_token: No autorizado, token de autorización inválido o faltante.
429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
500 api_error: Error interno del servidor, algo salió mal en el servidor.

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

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

Primeros pasos

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Avanzado

Solicitud y uso de la API de Claude Messages

Proceso de solicitud

Uso básico

Ejemplo de cURL

Ejemplo de Python

Mensaje del sistema

Ejemplo de Python

Respuesta en streaming

Ejemplo de Python

Ejemplo de JavaScript

Diálogo de múltiples turnos

Ejemplo de Python

Modelo de pensamiento profundo

Ejemplo de Python

Modelo visual

Usando imágenes codificadas en Base64

Usando imágenes de URL

cURL 示例

Uso de herramientas (Tool Use)

Ejemplo de Python

Diferencias con la API de Chat Completion

Manejo de errores

Ejemplo de respuesta de error

Conclusión

Primeros pasos

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Avanzado

​Proceso de solicitud

​Uso básico

​Ejemplo de cURL

​Ejemplo de Python

​Mensaje del sistema

​Ejemplo de Python

​Respuesta en streaming

​Ejemplo de Python

​Ejemplo de JavaScript

​Diálogo de múltiples turnos

​Ejemplo de Python

​Modelo de pensamiento profundo

​Ejemplo de Python

​Modelo visual

​Usando imágenes codificadas en Base64

​Usando imágenes de URL

​cURL 示例

​Uso de herramientas (Tool Use)

​Ejemplo de 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

Mensaje del sistema

Ejemplo de Python

Respuesta en streaming

Ejemplo de Python

Ejemplo de JavaScript

Diálogo de múltiples turnos

Ejemplo de Python

Modelo de pensamiento profundo

Ejemplo de Python

Modelo visual

Usando imágenes codificadas en Base64

Usando imágenes de URL

cURL 示例

Uso de herramientas (Tool Use)

Ejemplo de Python

Diferencias con la API de Chat Completion

Manejo de errores

Ejemplo de respuesta de error

Conclusión