Documentación de la API de Mensajes de Anthropic: Endpoints, Solicitudes, Visión y Backends de Agentes

La API de Mensajes de Anthropic es la principal interfaz HTTP para enviar indicaciones a Claude. El endpoint principal es POST /v1/messages: proporcionas un modelo, una lista de bloques de contenido de mensajes con tipo y un límite de tokens, y luego recibes un mensaje de asistente que contiene uno o más bloques de salida.

Esta guía convierte la documentación de la API de Anthropic en una lista de verificación de implementación. Cubre el contrato de solicitud, el estado de múltiples turnos, streaming, visión, la API de Archivos, el uso de herramientas y las opciones involucradas cuando un backend de agente necesita admitir tanto proveedores de modelos nativos de Anthropic como compatibles con OpenAI.

Endpoint de la API de Mensajes y Encabezados Requeridos

La API de Mensajes nativa de Anthropic utiliza este endpoint:

POST https://api.anthropic.com/v1/messages

Las solicitudes HTTP directas normalmente incluyen estos encabezados:

Encabezado	Propósito
x-api-key	Autentica la cuenta de Anthropic
anthropic-version	Selecciona el contrato de versión de API documentado
content-type: application/json	Declara un cuerpo de solicitud JSON

El encabezado de versión de la API no es una versión del modelo. Controla el comportamiento de la API HTTP, mientras que el campo model selecciona el modelo de Claude utilizado para la inferencia. Mantén ambos valores en la configuración en lugar de dispersarlos por el código de la aplicación.

La Estructura de Solicitud y Respuesta

Una solicitud básica contiene tres campos:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Explica las claves de idempotencia en dos párrafos."
    }
  ]
}

La respuesta es un mensaje de asistente en lugar de una cadena simple. Su propiedad content es un array de bloques con tipo, por lo que el código de producción debe inspeccionar el type de cada bloque antes de leer sus campos.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Una clave de idempotencia..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

Este diseño basado en bloques importa una vez que agregas imágenes o herramientas. Un solo turno de asistente puede contener texto y una solicitud de herramienta, y un turno de usuario puede contener texto junto con bloques de imagen o documento.

Una Solicitud curl Mínima

Almacena las credenciales en una variable de entorno y utiliza un ID de modelo actualmente disponible para tu cuenta de Anthropic:

export ANTHROPIC_API_KEY="tu-api-key"
export ANTHROPIC_MODEL="tu-id-de-modelo-claude"

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Devuelve tres formas prácticas de reducir la latencia de la API."
      }
    ]
  }'

No codifiques de forma fija un nombre de modelo copiado de un tutorial antiguo. La disponibilidad y los alias de los modelos pueden cambiar, por lo que la configuración de implementación debe usar un ID de modelo verificado en la documentación actual del modelo del proveedor o en la consola.

Uso en Python con el SDK de Anthropic

El SDK oficial de Python maneja los encabezados de autenticación y convierte la respuesta en objetos con tipo:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Escribe una función en Python que valide una cadena UUID.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Iterar sobre los bloques de contenido es más seguro que asumir que message.content[0] siempre es texto. Las aplicaciones de agente pueden recibir bloques de uso de herramientas, y las características multimodales pueden agregar otros tipos de bloques a la conversación.

Conversaciones de Múltiples Turnos e Instrucciones del Sistema

La API de Mensajes no tiene estado. Tu aplicación envía el historial de conversación relevante nuevamente con cada solicitud:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "Eres un asistente de documentación de API conciso.",
  "messages": [
    {"role": "user", "content": "¿Qué significa HTTP 429?"},
    {"role": "assistant", "content": "Indica limitación de velocidad."},
    {"role": "user", "content": "¿Cómo debería reintentar mi cliente?"}
  ]
}

Anthropic coloca la instrucción del sistema en el campo system de nivel superior en lugar de en un mensaje con role: "system". Esta es una de las diferencias importantes a tener en cuenta al traducir solicitudes de esquemas compatibles con OpenAI.

Para sesiones de larga duración, no reenvíes una transcripción ilimitada. Mantén los turnos más recientes, conserva las decisiones y los resultados de herramientas que aún afectan la tarea, y resume el contexto anterior antes de que la indicación se acerque al límite de contexto del modelo seleccionado.

Respuestas en Streaming

Establece stream: true cuando la interfaz deba mostrar la salida de forma incremental:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explica el pool de conexiones de bases de datos."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

El streaming mejora la latencia percibida, pero agrega trabajo de gestión de estado. Tu aplicación debe manejar una conexión que se cierra temprano, texto parcial, orden de eventos y metadatos de uso final. Para agentes que usan herramientas, almacena en búfer el bloque completo de entrada de la herramienta antes de analizarlo o ejecutarlo.

Solicitudes de la API de Visión de Claude

La API de Visión de Claude utiliza el mismo endpoint de Mensajes. Agrega un bloque de contenido de imagen antes de la pregunta de texto relacionada. Las imágenes se pueden proporcionar como datos base64 compatibles o a través de un tipo de fuente permitido descrito en la documentación de visión actual.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Identifica dos riesgos de confiabilidad en este diagrama de arquitectura.",
                },
            ],
        }
    ],
)

Cambia el tamaño de las imágenes demasiado grandes antes de enviarlas. Las imágenes grandes aumentan el tiempo de transferencia y el uso de tokens sin mejorar necesariamente la respuesta. También valida el tipo MIME; declarar datos JPEG como PNG es una causa común de solicitudes rechazadas.

Uso de la API de Archivos de Anthropic

La API de Archivos de Anthropic es útil cuando un archivo debe cargarse una vez y ser referenciado por llamadas posteriores a la API de Mensajes en lugar de codificarse y transmitirse repetidamente. La disponibilidad exacta, los tipos de archivo admitidos y los campos de solicitud pueden diferir según el estado de la función, por lo que debes consultar la documentación actual de la API de Archivos antes de confiar en ella en producción.

Una integración típica tiene dos etapas:

1. Carga el archivo y persiste el identificador de archivo devuelto con el registro de documento de tu aplicación.
2. Haz referencia a ese identificador en un bloque de contenido compatible al crear un mensaje.

Trata los IDs de archivo como recursos específicos del proveedor. Registra qué proveedor y cuenta crearon cada ID, aplica tus propios controles de acceso y define una política de eliminación. Un identificador de archivo no debe ser aceptado directamente de un usuario no confiable sin verificaciones de autorización.

Para imágenes pequeñas ocasionales, base64 es directo. Para documentos utilizados en muchas solicitudes, un recurso de archivo del proveedor puede reducir las cargas repetidas. Si tu aplicación debe funcionar con múltiples proveedores, mantén el objeto original en tu propio almacenamiento y crea IDs de archivo específicos del proveedor como un caché.

Uso de Herramientas para Backends de Agentes

Las herramientas permiten que Claude solicite una función definida por la aplicación. Tu backend describe cada herramienta con un nombre, un propósito y un contrato de entrada de esquema JSON. El modelo puede entonces devolver un bloque tool_use en lugar de pretender que ejecutó la operación.

{
  "name": "get_order_status",
  "description": "Consulta el estado actual de un pedido de cliente.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "El identificador del pedido mostrado al cliente."
      }
    },
    "required": ["order_id"]
  }
}

El bucle de ejecución seguro es:

1. Envía mensajes y definiciones de herramientas al modelo.
2. Detecta un bloque de contenido tool_use.
3. Valida su entrada contra el esquema y tus reglas de autorización.
4. Ejecuta la herramienta en un entorno controlado.
5. Devuelve un bloque tool_result coincidente en el siguiente turno de usuario.
6. Continúa hasta que el modelo produzca una respuesta normal o alcance tu límite de bucle.

Nunca ejecutes argumentos de herramientas como comandos de shell, SQL o rutas de archivo de confianza. Para agentes de codificación, ejecuta los comandos generados dentro de un entorno aislado como Novita Agent Sandbox, con límites explícitos de tiempo, red, sistema de archivos y recursos.

Solicitudes Nativas de Anthropic vs. Solicitudes Compatibles con OpenAI

Las API nativas de Anthropic y las compatibles con OpenAI resuelven el mismo problema general, pero sus formatos de transmisión no son idénticos.

Aspecto	API de Mensajes de Anthropic	API de chat compatible con OpenAI
Endpoint común	/v1/messages	/v1/chat/completions
Instrucción del sistema	Campo system de nivel superior	Comúnmente un mensaje system o developer
Representación de salida	Bloques de contenido con tipo	Comúnmente choices[].message
Solicitud de herramienta	Bloque tool_use	Comúnmente tool_calls
Resultado de herramienta	Bloque de contenido tool_result	Comúnmente un mensaje con rol tool

Un endpoint compatible con OpenAI es valioso cuando tu aplicación ya usa el SDK de OpenAI o necesita cambiar entre modelos de código abierto con cambios mínimos de transporte. Novita AI expone una API LLM compatible con OpenAI, por lo que la misma estructura de cliente puede apuntar a múltiples modelos disponibles cambiando la URL base y la configuración del modelo.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Revisa esta estrategia de reintento para modos de fallo.",
        }
    ],
)

print(response.choices[0].message.content)

Esto no es una traducción directa de cada característica de Anthropic. Si tu aplicación depende de bloques de contenido específicos de Anthropic, semántica de herramientas, citas o funciones beta, mantén un adaptador nativo de Anthropic. Usa la ruta compartida compatible con OpenAI para cargas de trabajo que se ajusten a su modelo de solicitud común.

Construyendo un Backend de Agente Neutro Respecto al Proveedor

Un backend neutro respecto al proveedor debe normalizar los conceptos de la aplicación sin pretender que todos los proveedores son idénticos. Un diseño práctico tiene cuatro capas:

1. Modelo de conversación: almacena roles, texto, imágenes, llamadas a herramientas y resultados de herramientas en un esquema interno.
2. Adaptador de proveedor: traduce el esquema interno a cargas útiles de Mensajes de Anthropic o compatibles con OpenAI.
3. Registro de capacidades: rastrea si el modelo seleccionado admite visión, herramientas, salida estructurada u otro comportamiento requerido.
4. Capa de ejecución: ejecuta herramientas y código por separado del proveedor de inferencia.

Esta separación permite que un equipo use Claude donde el comportamiento nativo de Anthropic es importante, mientras enruta cargas de trabajo compatibles a un modelo de código abierto a través de Novita AI. La ruta de código abierto puede ser útil para el control de costos, la experimentación con modelos, los requisitos de ubicación de datos o para evitar la dependencia de un solo proveedor. Prueba la calidad de la salida y la confiabilidad de las herramientas en tus propias tareas en lugar de asumir que dos modelos son intercambiables porque ambos aceptan mensajes de chat.

Para cargas de trabajo de agentes, la capa de ejecución merece la misma atención. El cambio de modelo no protege tu infraestructura de comandos inseguros. Usa un sandbox aislado, aplica listas blancas de herramientas, limita las iteraciones y registra cada decisión del modelo y resultado de la herramienta con las credenciales eliminadas.

Errores Comunes y Depuración

400 Bad Request

Verifica la forma del JSON, los tipos de bloques de contenido, los campos requeridos y si el modelo seleccionado admite la función solicitada. Registra el ID de solicitud del proveedor y el cuerpo del error estructurado, pero redacta las credenciales y los datos de archivo en base64.

401 Error de Autenticación

Confirma que la clave API está presente en el entorno de ejecución y pertenece al proveedor previsto. Anthropic usa x-api-key para solicitudes HTTP directas; un cliente compatible con OpenAI generalmente envía un token de portador automáticamente.

404 Modelo o Recurso No Encontrado

Verifica el ID del modelo con la documentación actual del proveedor o la consola. Para los recursos de la API de Archivos, también verifica que el archivo pertenezca a la misma cuenta y entorno utilizados por la solicitud.

429 Límite de Velocidad

Reintenta con retroceso exponencial y fluctuación, pero limita el número de intentos. Pon en cola el trabajo en segundo plano, limita la concurrencia por proveedor y evita reintentar inmediatamente cada solicitud fallida al mismo intervalo.

Errores de Límite de Contexto o Tokens

Reduce el historial de conversación, el tamaño de la imagen, el contenido del archivo o la longitud de salida solicitada. Cuenta toda la solicitud, incluidas las instrucciones del sistema, los esquemas de herramientas, los resultados de herramientas anteriores y el contenido multimodal.

Artículos Recomendados

• ¿Qué son los Agentes de Codificación? Arquitectura, Herramientas y Bucles de Ejecución
• ¿Qué es MCP? Guía para Desarrolladores del Protocolo de Contexto de Modelo
• Guía de LLM de Código Abierto 2026: Modelos, Compensaciones e Implementación

Lista de Verificación de Implementación

• Mantén las claves API, los IDs de modelo, las URL base y las versiones de API en la configuración de tiempo de ejecución.
• Analiza los bloques de contenido con tipo en lugar de asumir una sola cadena de texto.
• Almacena suficiente estado de conversación para reconstruir cada solicitud sin estado.
• Valida las entradas de las herramientas y ejecútalas fuera del proceso del modelo.
• Agrega tiempos de espera, límites de reintento, IDs de solicitud y observabilidad con datos redactados.
• Condiciona el enrutamiento del proveedor por capacidad del modelo, no solo por precio o nombre.
• Vuelve a verificar los IDs de modelo, el estado de las funciones, los límites y los precios antes de la implementación.

La API de Mensajes es sencilla en la capa HTTP. El trabajo de ingeniería más difícil aparece cuando una aplicación agrega streaming, entrada multimodal, herramientas, archivos persistentes o múltiples proveedores de modelos. Mantén esas preocupaciones detrás de adaptadores explícitos, y tu backend de agente puede evolucionar sin vincular la lógica de negocio a un formato de solicitud.

Preguntas Frecuentes

¿Cuál es el endpoint de la API de Mensajes de Anthropic?

El endpoint nativo es POST https://api.anthropic.com/v1/messages. Las solicitudes requieren autenticación, un encabezado de versión de API de Anthropic, un ID de modelo, un límite de tokens y un array de mensajes.

¿Es la API de Mensajes de Anthropic compatible con OpenAI?

No. Los conceptos se superponen, pero las instrucciones del sistema, los bloques de contenido, los objetos de respuesta y los mensajes de uso de herramientas difieren. Usa un adaptador de proveedor si una aplicación necesita admitir ambos formatos.

¿La API de Visión de Claude usa un endpoint separado?

No. Las solicitudes de visión usan la API de Mensajes con bloques de contenido de imagen y texto. El modelo de Claude seleccionado debe admitir la entrada de imágenes.

¿Cuándo debo usar la API de Archivos de Anthropic?

Úsala cuando los archivos compatibles necesiten ser referenciados a través de solicitudes y las cargas repetidas en base64 sean desperdiciadas. Mantén tu propio archivo fuente y registro de autorización porque los IDs de archivo del proveedor son recursos específicos de la cuenta.

¿Puede Claude Code usar un backend de API personalizado?

La integración de Claude Code depende de la autenticación y la configuración del proveedor admitidas por la versión actual de Claude Code. No asumas que un endpoint compatible con OpenAI implementa la API de Mensajes de Anthropic. Para un agente personalizado, un adaptador neutro respecto al proveedor suele ser más claro que intentar hacer que diferentes protocolos parezcan idénticos.

¿Cuándo debo elegir un modelo de código abierto a través de Novita AI?

Considérelo cuando quieras cambiar de modelo compatible con OpenAI, experimentar con modelos abiertos o tener un segundo proveedor para cargas de trabajo compatibles. Mantén las solicitudes nativas de Anthropic para funciones que requieran un comportamiento específico de la API de Claude, y evalúa ambas rutas con tus propias indicaciones y herramientas.