Guía de la API de Kimi K3: Python, visión, herramientas y contexto de 1M

Kimi K3 está disponible mediante la API de Chat Completions compatible con OpenAI de Moonshot AI, utilizando el ID de modelo kimi-k3. La API admite razonamiento siempre activo, streaming, imágenes, vídeos subidos, JSON Schema estricto, herramientas personalizadas, carga dinámica de herramientas y una ventana de contexto de 1 millón de tokens.

La compatibilidad no implica un comportamiento idéntico. K3 utiliza valores de muestreo fijos, requiere conservar el estado completo del asistente en turnos posteriores con herramientas y conversaciones, y gestiona el razonamiento por separado del contenido final. Esta guía se centra en esos detalles.

Disponibilidad y precios actualizados el 22 de julio de 2026. Kimi K3 está disponible en Poyo.ai como kimi-k3 mediante la API Chat Completions compatible con OpenAI. El precio es de $2.28 por 1M tokens de entrada y $11.40 por 1M tokens de salida, un 24 % menos que el precio oficial.

Requisitos

Necesitas:

• Python 3.9 o superior;
• el paquete Python openai versión 1.0 o superior;
• una clave API de Moonshot almacenada fuera del control de versiones;
• la URL base https://api.moonshot.ai/v1;
• el ID de modelo kimi-k3.

Instala el SDK:

python -m pip install --upgrade "openai>=1.0"

Configura la clave en tu shell:

export MOONSHOT_API_KEY="your-key"

En PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Nunca incluyas una clave de producción en un ejemplo de código, un paquete del lado del cliente, un registro o un repositorio.

Realiza tu primera solicitud a Kimi K3

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Review this migration plan and list its three highest risks."}
    ],
)

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

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
    ]
  }'

Configura el esfuerzo de razonamiento

K3 utiliza siempre el modo de razonamiento. Configura su nivel mediante el campo de nivel superior reasoning_effort:

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[
        {"role": "user", "content": "Find the flaw in this distributed lock design."}
    ],
)

Los valores admitidos son:

Valor	Uso recomendado
low	Tareas más sencillas donde importan la latencia y la salida
high	Programación compleja, análisis y planificación de herramientas
max	Las tareas más difíciles y evaluaciones tipo benchmark

El valor predeterminado documentado es max. No asumas que es la configuración de producción más económica. Evalúa la tasa de éxito, la latencia y los tokens generados con cada nivel de esfuerzo.

Transmite el razonamiento y el contenido final

Las respuestas en streaming exponen el razonamiento y el texto final mediante diferentes campos delta.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Store or process according to your product and provider policies.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)

Mantén separado el contenido final visible para usuarios del procesamiento interno. No extraigas salidas estructuradas desde reasoning_content.

Envía una imagen a Kimi K3

Los mensajes con visión de K3 utilizan un array de objetos de contenido. Las URL de imágenes públicas no son compatibles con este flujo; codifica una imagen local en base64.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {
                    "type": "text",
                    "text": "Identify the three largest accessibility problems in this interface.",
                },
            ],
        }
    ],
)

Valida el tipo y el tamaño del archivo antes de codificar las cargas de usuarios. Evita registrar cargas base64.

Envía un vídeo a Kimi K3

Sube el vídeo mediante la API de Files, referencia el ID devuelto con el esquema ms:// y elimina el archivo cuando ya no sea necesario.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")

try:
    response = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize the workflow and identify failed steps."},
                ],
            }
        ],
    )
finally:
    client.files.delete(video.id)

Devuelve una salida con JSON Schema estricto

Usa strict: true cuando el código posterior necesite una estructura predecible.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "incident_risk",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "risk": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "owner": {"type": ["string", "null"]},
                },
                "required": ["risk", "severity", "owner"],
                "additionalProperties": False,
            },
        },
    },
)

result = json.loads(response.choices[0].message.content or "{}")

Analiza únicamente el message.content final y valida de nuevo el resultado en el código de la aplicación.

Llama a herramientas personalizadas

La primera respuesta puede solicitar una o varias herramientas. Ejecuta cada llamada permitida, añade el mensaje completo del asistente y después añade un resultado de herramienta coincidente para cada tool_call_id.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_build_status",
            "description": "Return the current build status for an allowed project.",
            "parameters": {
                "type": "object",
                "properties": {"project": {"type": "string"}},
                "required": ["project"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)
    # Authorize and validate before executing a real tool.
    tool_result = {"project": arguments["project"], "status": "passed"}
    messages.append(
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(tool_result),
        }
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)

Nunca ejecutes comandos shell generados arbitrariamente por el modelo sin un límite de permisos, validación de entradas, un entorno controlado y un registro de auditoría.

Carga herramientas dinámicamente

K3 permite colocar una definición completa de herramienta en un mensaje system en el momento en que está disponible. Conserva ese mensaje en el historial posterior porque el servidor no lo mantiene por ti.

La carga dinámica ayuda a los sistemas de agentes grandes a evitar enviar todos los esquemas de herramientas en cada turno. También crea nuevos requisitos de gestión de estado: el modelo debe ver la declaración exacta al interpretar resultados posteriores de herramientas.

Usa la ventana de contexto de 1M tokens

Los contextos grandes son más valiosos cuando es necesario razonar conjuntamente sobre información distante. Utilízalos de forma deliberada:

1. Mantén repositorios estables o corpus de documentos al principio.
2. Añade preguntas y resultados en lugar de reescribir el prefijo.
3. Realiza un seguimiento separado de entradas almacenadas en caché y no almacenadas.
4. Recupera un subconjunto menor cuando no sea necesario utilizar todo el corpus.
5. Establece identificadores de origen para que la respuesta final pueda verificarse.
6. Compacta únicamente cuando tu cliente conserve todo el estado necesario para K3.

La caché automática no tiene un ID de caché ni un parámetro TTL convencional. Los prefijos estables ofrecen al servicio la mejor oportunidad de aprovechar la caché.

Conserva el estado completo en conversaciones con varios turnos

Esta es la regla de integración más importante específica de K3.

Al continuar una conversación o devolver resultados de herramientas, añade el mensaje completo del asistente devuelto por la API. No conserves únicamente content. Moonshot advierte que K3 fue entrenado con el historial de razonamiento conservado y puede volverse inestable si el sistema elimina el historial necesario o cambia a K3 a mitad de una sesión.

Almacena el estado de la conversación de forma segura, aplica límites de retención y evita exponer estados ocultos a usuarios que no deberían verlos.

Límites importantes de la API de Kimi K3

• K3 siempre tiene el razonamiento activado.
• reasoning_effort admite low, high y max.
• max_completion_tokens tiene un valor predeterminado de 131,072 y puede establecerse hasta 1,048,576.
• temperature=1.0, top_p=0.95, n=1, presence_penalty=0 y frequency_penalty=0 son valores fijos; omítelos.
• Las URL públicas de imágenes no son compatibles con mensajes de visión.
• Las solicitudes con varios turnos y herramientas deben conservar el mensaje completo del asistente.
• Moonshot indica que su herramienta de búsqueda web está siendo actualizada y actualmente no se recomienda para producción.

Lista de comprobación para producción

• Mantén las claves API en el servidor.
• Añade tiempos de espera para solicitudes y reintentos limitados.
• Valida los argumentos de las herramientas y autoriza cada acción.
• Limita los turnos de herramientas y la longitud de finalización.
• Conserva el estado completo del asistente de K3.
• Valida el JSON estricto después de la generación.
• Registra entrada, entrada en caché, salida, latencia y errores.
• Evita cambiar de modelo a mitad de una sesión de K3.
• Añade límites de comportamiento explícitos para reducir una proactividad excesiva.
• Prueba con herramientas dañadas, respuestas parciales e historiales extensos.

Lee Precios de la API de Kimi K3 antes de elegir los límites de contexto y salida. Consulta la página del modelo Kimi K3 para conocer la disponibilidad de Poyo.ai.

Preguntas frecuentes

¿La API de Kimi K3 es compatible con OpenAI?

Sí. Moonshot ofrece un endpoint de Chat Completions compatible con OpenAI. Las reglas específicas de K3 sobre estado, razonamiento, muestreo y medios siguen siendo aplicables.

¿Cuál es el ID del modelo Kimi K3?

El ID oficial del modelo de la API de Moonshot es kimi-k3.

¿Kimi K3 admite llamadas a funciones?

Sí. Admite herramientas personalizadas, selección de herramientas obligatoria, resultados de herramientas coincidentes y carga dinámica de herramientas.

¿Puede Kimi K3 procesar vídeos?

Sí. Sube el vídeo mediante la API de Files y referencia su ID de archivo ms:// en un objeto de contenido de vídeo.

¿Cómo utilizo la ventana de contexto de 1M?

Envía los mensajes y contenidos necesarios mediante la solicitud estándar del modelo, mantén los prefijos estables sin cambios para la caché automática y establece límites de finalización controlados.

Fuentes

• Guía rápida oficial de la API de Kimi K3
• Precios oficiales de Kimi K3
• Página del modelo Kimi K3 de Poyo.ai