API Messages

Endpoint: POST /v1/messages. La solicitud y la respuesta coinciden exactamente con la API Messages de Anthropic, por lo que el SDK de Anthropic —o cualquier herramienta compatible con esa API— funciona con Kunavo cambiando solo la URL base y la clave.

¿Qué endpoint debería usar?

Kunavo ofrece la familia Claude de dos maneras. Ambas tienen el mismo coste; elige según el formato de solicitud que ya use tu código.

Autenticación

Configura la URL base como https://api.kunavo.com: el SDK de Anthropic añade /v1/messages por sí mismo. Pasa tu clave de Kunavo (sk-kn-...) como clave de API; el endpoint la acepta en el encabezado x-api-key (el predeterminado del SDK de Anthropic) o en Authorization: Bearer.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",                  # your Kunavo key
    base_url="https://api.kunavo.com",    # SDK appends /v1/messages
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a senior staff engineer.",
    messages=[
        {"role": "user", "content": "Pros and cons of event sourcing?"},
    ],
)
print(msg.content[0].text)

caché de prompts

Esta es la razón principal para usar el endpoint nativo. Añade un punto de ruptura cache_control a cualquier bloque de sistema, bloque de contenido de mensaje o definición de herramienta. El prefijo marcado se guarda en la caché una vez y luego se reutiliza en las llamadas posteriores que lo comparten.

El almacenamiento en caché en sí no necesita este endpoint: en /v1/chat/completions y /v1/responses, Kunavo establece por sí mismo los puntos de ruptura para los modelos Claude en un prompt largo. Lo que este endpoint hace distinto es no añadir ninguno: el cuerpo de la solicitud se transmite tal como lo enviaste, así que cada punto de ruptura que contiene lo pusiste tú.

# Mark a large, stable prefix with cache_control. The first call writes that
# span to cache at 1.25× the input token price; later calls that reuse it read
# it back at ~10%.
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STYLE_GUIDE,            # tens of thousands of tokens
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Review this PR against the guide."}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens)

Precios de la familia Claude en Kunavo:

• cache_read_input_tokens — se sirve desde la caché y se factura a 0.10× de la tarifa de entrada (un descuento del 90%); 0,025× en Claude Fable 5.1, 0,05× en Claude Opus 5.5.
• cache_creation_input_tokens — se escribe en la caché y se factura a 1.25× la tarifa de entrada. Kunavo factura las escrituras con TTL de 1 hora a la misma tarifa de 1.25×, por debajo de la tarifa de 2× de Anthropic.

Streaming

Establece stream: true (o usa el asistente stream() del SDK). Kunavo retransmite literalmente el flujo de eventos nativo de Anthropic: message_start, content_block_delta, message_delta, message_stop.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain CRDTs in one paragraph."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Imágenes

Envía imágenes como fuentes base64 o url. Una fuente url es la única parte del cuerpo de la solicitud que Kunavo reescribe: descarga por sí mismo una imagen https (o desempaqueta un URI data:) y la reenvía como base64, porque el servicio upstream ignora una fuente url y respondería como si no se hubiera enviado ninguna imagen. Las imágenes dentro de un tool_result se procesan de la misma manera. Límites: 16 imágenes por solicitud, 5 MB por imagen y 20 MB en total; si no se puede obtener una imagen, se devuelve un error en lugar de omitirla.

Objeto de uso

Cada respuesta (y los eventos de streaming message_delta / message_start) incluye un objeto usage nativo de Anthropic:

Herramientas del servidor

Las herramientas del servidor de Anthropic (web_search, web_fetch, code_execution) se transmiten como definiciones de herramientas ordinarias. El contenido que añaden a la conversación (resultados de búsqueda, una página obtenida, la salida de un programa) vuelve en usage como tokens y se factura según las tarifas anteriores.

La búsqueda web también se factura por búsqueda, además de esos tokens: Anthropic la anuncia a $10 por cada 1,000 búsquedas, y Kunavo aplica el descuento propio de cada modelo a ese importe. El recuento está en usage.server_tool_use.web_search_requests, en la respuesta o en el message_delta final de un flujo; no se cuenta una búsqueda que devuelva un error (como max_uses_exceeded). La obtención de páginas web y la ejecución de código no tienen coste adicional aparte de los tokens.

Modelos compatibles

Cualquier modelo Claude habilitado acepta /v1/messages. Envía el slug de Kunavo como model:

• claude-fable-5, claude-sonnet-5
• claude-opus-5, claude-opus-4-7, claude-opus-4-6
• claude-sonnet-4-6, claude-haiku-4-5

Los modelos GPT no están disponibles aquí; llámalos mediante /v1/chat/completions.

HTTP sin procesar

No hace falta un SDK: el endpoint acepta un POST JSON sin formato:

curl https://api.kunavo.com/v1/messages \
  -H "x-api-key: sk-kn-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Próximos pasos

• Finalizaciones de chat compatibles con OpenAI
• Cómo funciona la facturación (precios por token, tarifas de caché, recargo)
• Explorar todos los modelos de chat