Texto

Create Message

Crea un mensaje utilizando el formato de la API de Anthropic Messages

POST
/v1/messages

Descripción general

Este endpoint acepta el formato nativo de Anthropic Messages, por lo que los SDK de Anthropic y las herramientas creadas sobre ellos funcionan con la URL base de TokenLab. Funciona con modelos cuyos accepted_request_formats incluyen anthropic_messages: modelos Claude y algunos otros modelos.

messages contiene los turnos de user y assistant. Coloque las instrucciones del sistema en el campo system de nivel superior. max_tokens es obligatorio. Para mensajes al estilo de OpenAI con roles como system o tool, utilice Chat Completions.

URL base para el SDK de Anthropic: https://api.tokenlab.sh (sin el sufijo /v1)

Encabezados de solicitud

x-api-keystringheader

Su clave de API de TokenLab. Envíe x-api-key o Authorization: Bearer <API_KEY>. Si envía ambos con valores diferentes, TokenLab utiliza x-api-key.

anthropic-versionstringheader

Versión de la API de Anthropic. Los SDK de Anthropic la envían por usted; utilice 2023-06-01 cuando llame a la API directamente.

anthropic-betastringheader

Nombres de las funciones beta de Anthropic, separados por comas. TokenLab pasa el encabezado, y si una función beta funciona o no depende del modelo. El contenido que hace referencia a un file_id necesita files-api-2025-04-14.

Cuerpo de la solicitud

Los parámetros opcionales admitidos, los valores aceptados y los valores predeterminados dependen del modelo seleccionado. Consulte los detalles del modelo antes de configurar las opciones de muestreo, razonamiento o herramientas.

modelstringobligatorio

ID de un modelo que admite el formato anthropic_messages. Consulte los detalles del modelo para conocer las capacidades actuales.

messagesarrayobligatorio

Matriz de objetos de mensaje con role (user o assistant) y content. Hasta 100,000 mensajes.

content puede ser una cadena de texto simple o una matriz de bloques de contenido. Para enviar imágenes, utilice bloques de contenido estructurados en lugar de colocar URL de imágenes o cadenas Base64 directamente en texto plano. Se aceptan otros bloques nativos, como tool_use, tool_result, thinking y document, para los modelos que los admiten.

Ejemplos de bloques de contenido:

  • bloque de texto: { "type": "text", "text": "Describe esta imagen" }
  • bloque de imagen mediante URL: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • bloque de imagen mediante Base64: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerobligatorio

Máximo de tokens a generar. Obligatorio: TokenLab no añade un valor predeterminado. El máximo utilizable depende del modelo; consulte max_output_tokens en sus detalles del modelo. Un valor grande aumenta la cantidad que TokenLab retiene de su saldo mientras se ejecuta la solicitud, y un saldo que no puede cubrir la retención devuelve 402.

systemstring | array

Prompt del sistema como una cadena o una matriz de bloques de contenido de texto, separado de la matriz messages.

temperaturenumber

Temperatura de muestreo. La compatibilidad, los valores permitidos y el valor predeterminado dependen del modelo seleccionado; omita este campo para usar su valor predeterminado.

streambooleanpredeterminado: false

Devuelve la respuesta como un flujo de eventos enviados por el servidor (SSE). Consulte Streaming.

thinkingobject

Configuración de pensamiento nativa, por ejemplo {"type":"enabled","budget_tokens":10000}. Los modos, presupuestos y combinaciones con otros parámetros admitidos dependen del modelo seleccionado. Para un modelo que se sabe que rechaza un presupuesto manual, TokenLab ejecuta {"type":"enabled"} como pensamiento adaptativo e ignora budget_tokens.

toolsarray

Herramientas disponibles para el modelo. La compatibilidad depende del modelo seleccionado.

tool_choiceobject

Objeto de elección de herramienta nativo, por ejemplo {"type":"auto"}. Los tipos admitidos dependen del modelo seleccionado.

cache_controlobject

Marcador de caché de prompt, por ejemplo {"type":"ephemeral"}; añada "ttl": "1h" para una caché de una hora. En el nivel superior, activa el almacenamiento en caché automático. También puede configurarlo en bloques system, tools y bloques de contenido. La compatibilidad depende del modelo; los modelos que lo admiten enumeran prompt-cache en capabilities.

top_pnumber

Parámetro de muestreo de núcleo (nucleus sampling). Utilice temperatura o top_p, no ambos. La compatibilidad depende del modelo seleccionado.

top_kinteger

Muestrear solo de las K opciones principales para cada token. La compatibilidad depende del modelo seleccionado.

stop_sequencesarray

Secuencias de parada personalizadas que harán que el modelo deje de generar. Hasta 8,191 entradas.

metadataobject

Metadatos de solicitud en el formato de Anthropic. user_id es un identificador opaco para su usuario final.

service_tierstring

Solo auto y standard_only tienen efecto. TokenLab solo cobra el nivel estándar e ignora cualquier otro valor.

Respuesta

idstring

Identificador único del mensaje.

typestring

Siempre message.

rolestring

Siempre assistant.

contentarray

Matriz de bloques de contenido, como text, thinking o tool_use.

modelstring

Modelo que produjo la respuesta.

stop_reasonstring

Razón por la que se detuvo la generación, como end_turn, max_tokens, stop_sequence o tool_use. Un modelo puede devolver otros valores, por ejemplo refusal.

stop_sequencestring | null

La secuencia de parada que finalizó la generación, o null.

usageobject

Uso de tokens con input_tokens y output_tokens. Cuando el modelo informa tokens de caché de prompt, usage también tiene cache_creation_input_tokens y cache_read_input_tokens.

Cada respuesta lleva el ID de solicitud en los encabezados request-id y X-Request-ID. Cítelo cuando se ponga en contacto con el soporte.

Solicitud

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Respuesta

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Ejemplo de entrada de visión

Para modelos Claude con soporte de visión, coloque las imágenes dentro de messages[].content como bloques de imagen estructurados.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Ejemplo de pensamiento extendido

Utilice un modelo con la capacidad reasoning. Ajuste max_tokens y budget_tokens a los límites del modelo; algunos modelos necesitan una configuración de pensamiento diferente.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Streaming

Establezca "stream": true para recibir eventos enviados por el servidor de Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta y message_stop. El uso de tokens llega en message_start y message_delta.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • Mientras el modelo trabaja, el flujo puede transportar líneas de comentarios SSE como : keep-alive. Los SDK los ignoran.
  • El estado HTTP ya puede ser 200 cuando ocurre un fallo. Un fallo después de que el flujo haya comenzado llega como un evento event: error con el mismo cuerpo de error que se muestra a continuación.

Errores

Los errores utilizan el formato de error de Anthropic. request_id es el ID de solicitud de TokenLab. Algunos errores añaden campos como code y hint.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
Estadoerror.typeCausa típica
400invalid_request_errorUn campo faltante o no válido, un modelo desconocido o un modelo que no acepta el formato Messages
401authentication_errorLa clave de API falta o no es válida
402billing_errorEl saldo no puede cubrir la solicitud (error.code es insufficient_balance). Una clave de API en su límite de gasto también obtiene 402, con error.code quota_exceeded y error.type rate_limit_error
403permission_errorLa clave de API no puede utilizar el modelo solicitado, o la cuenta está suspendida o restringida
409conflict_errorUn reintento con la misma Idempotency-Key. Consulte Reintentar de forma segura con una clave de idempotencia
413request_too_largeLa entrada de la solicitud es demasiado grande
429rate_limit_errorDemasiadas solicitudes
500, 502, 503api_error o overloaded_errorLa solicitud no pudo completarse, o no hay ninguna ruta disponible para ella en este momento. Vuelva a intentarlo más tarde
504timeout_errorLa solicitud ha caducado

Interfaces relacionadas

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clave opcional que detiene una segunda ejecución de la misma solicitud. Envíe un nuevo valor único, como un UUID, para cada solicitud y consérvelo para reintentos después de un tiempo de espera. Un reintento con la misma clave no se ejecuta de nuevo: devuelve 409 con idempotency_replay_unavailable, o generalmente idempotency_conflict cuando el cuerpo ha cambiado. Excepción: cuando un resultado que no es de streaming finaliza después de que el cliente se desconectó, un reintento con la misma clave y cuerpo dentro de las 24 horas devuelve ese resultado (hasta 1 MB) con el encabezado Idempotent-Replayed: true y sin un segundo cargo. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json