Texto
Create Message
Crea un mensaje utilizando el formato de la API de Anthropic 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
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.
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.
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.
ID de un modelo que admite el formato anthropic_messages. Consulte los detalles del modelo para conocer las capacidades actuales.
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..." } }
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.
Prompt del sistema como una cadena o una matriz de bloques de contenido de texto, separado de la matriz messages.
Temperatura de muestreo. La compatibilidad, los valores permitidos y el valor predeterminado dependen del modelo seleccionado; omita este campo para usar su valor predeterminado.
falseDevuelve la respuesta como un flujo de eventos enviados por el servidor (SSE). Consulte Streaming.
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.
Herramientas disponibles para el modelo. La compatibilidad depende del modelo seleccionado.
Objeto de elección de herramienta nativo, por ejemplo {"type":"auto"}. Los tipos admitidos dependen del modelo seleccionado.
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.
Parámetro de muestreo de núcleo (nucleus sampling). Utilice temperatura o top_p, no ambos. La compatibilidad depende del modelo seleccionado.
Muestrear solo de las K opciones principales para cada token. La compatibilidad depende del modelo seleccionado.
Secuencias de parada personalizadas que harán que el modelo deje de generar. Hasta 8,191 entradas.
Metadatos de solicitud en el formato de Anthropic. user_id es un identificador opaco para su usuario final.
Solo auto y standard_only tienen efecto. TokenLab solo cobra el nivel estándar e ignora cualquier otro valor.
Respuesta
Identificador único del mensaje.
Siempre message.
Siempre assistant.
Matriz de bloques de contenido, como text, thinking o tool_use.
Modelo que produjo la respuesta.
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.
La secuencia de parada que finalizó la generación, o null.
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
{
"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
200cuando ocurre un fallo. Un fallo después de que el flujo haya comenzado llega como un eventoevent: errorcon 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"
}| Estado | error.type | Causa típica |
|---|---|---|
| 400 | invalid_request_error | Un campo faltante o no válido, un modelo desconocido o un modelo que no acepta el formato Messages |
| 401 | authentication_error | La clave de API falta o no es válida |
| 402 | billing_error | El 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 |
| 403 | permission_error | La clave de API no puede utilizar el modelo solicitado, o la cuenta está suspendida o restringida |
| 409 | conflict_error | Un reintento con la misma Idempotency-Key. Consulte Reintentar de forma segura con una clave de idempotencia |
| 413 | request_too_large | La entrada de la solicitud es demasiado grande |
| 429 | rate_limit_error | Demasiadas solicitudes |
| 500, 502, 503 | api_error o overloaded_error | La solicitud no pudo completarse, o no hay ninguna ruta disponible para ella en este momento. Vuelva a intentarlo más tarde |
| 504 | timeout_error | La solicitud ha caducado |
Interfaces relacionadas
- Contar tokens de mensaje: estime los tokens de entrada de una solicitud antes de enviarla.
- Los lotes de mensajes (Message Batches) ejecutan muchas solicitudes de Messages de forma asíncrona: crear, listar, recuperar, cancelar, obtener resultados y eliminar.
Autorización
BearerAuth Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
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"
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.
1 <= length <= 255Cuerpo 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