La API de Qwen4-Max ya está disponible en QwenCloud como un modelo de pago por token con el ID qwen4-max. Crea una clave de pago por uso en tu región, apunta el SDK de OpenAI a https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 (Singapur) y haz la llamada. Cuesta 1,50 $ por millón de tokens de entrada y 4,50 $ por millón de tokens de salida, con una ventana de contexto de 1M de tokens.
Esta guía cubre la clave, las URL base, el modo de razonamiento (thinking), la visión, las herramientas, las salidas estructuradas, el caché, la ruta de Anthropic, los límites y los errores. Todos los fragmentos de código siguen la documentación de QwenCloud tal como se leía el 16 de noviembre de 2026.
Para más contexto, lee qué es Qwen4-Max. Para acceder mediante suscripción en lugar de pago por token, consulta todas las formas de usar Qwen4-Max y la guía del Token Plan.
Qué te ofrece la API de Qwen4-Max
La API de Qwen4-Max es el modelo insignia de Alibaba servido a través de QwenCloud con endpoints compatibles con OpenAI, Anthropic y DashScope. Acepta texto, imágenes y video como entrada, devuelve texto, razona antes de responder de forma predeterminada y admite function calling, salidas estructuradas, caché de contexto, trabajos por lotes, búsqueda web y fine-tuning.
Estas son las cifras de la página del modelo qwen4-max:
| Elemento | Valor |
|---|---|
| ID del modelo | qwen4-max |
| Precio de entrada | 1,50 $ por 1M de tokens |
| Precio de salida | 4,50 $ por 1M de tokens |
| Caché implícito de entrada / lectura de caché explícito | 0,075 $ por 1M de tokens |
| Creación de caché explícito | 1,875 $ (5 minutos) o 3 $ (1 hora) por 1M de tokens |
| Ventana de contexto | 1M de tokens |
| Entrada máxima | 991K (983K con thinking) |
| Salida máxima | 393K |
| Razonamiento máximo | 262K |
| Rendimiento | 5.000.000 TPM |
Los tokens de thinking se facturan como tokens de salida. Para un desglose completo de costos, consulta la guía de precios de Qwen4-Max.
Consigue una clave y elige la URL base correcta
Las claves están vinculadas a una región, y el tipo de clave debe coincidir con el endpoint.
- Abre la consola de QwenCloud y elige una región en el selector de la esquina superior derecha.
- Ve a API Keys, haz clic en Create API key, añade una descripción y haz clic en Generate Key.
- Copia la clave de inmediato. Solo se muestra una vez. Las nuevas claves de pago por uso empiezan con
sk-ws-. - Expórtala:
export DASHSCOPE_API_KEY="sk-ws-...".
Cada región usa el dominio {region}.maas.qwencloudapi.com. Singapur es ap-southeast-1; Fráncfort es eu-central-1, Tokio es ap-northeast-1 y EE. UU. (Virginia) es us-east-1. Después añade la ruta del protocolo:
| Protocolo | URL base (Singapur) |
|---|---|
| Compatible con OpenAI (Chat Completions, Responses) | https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 |
| Compatible con Anthropic | https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic |
| DashScope HTTP | https://ap-southeast-1.maas.qwencloudapi.com/api/v1 |
Una clave del Token Plan (sk-sp-) solo funciona en token-plan.maas.qwencloudapi.com, y una clave de pago por uso solo funciona en el dominio de su propia región. Mezclarlas genera un error 401. Consulta las regiones y endpoints.
Tu primera llamada a la API de Qwen4-Max
Instala el SDK de OpenAI (pip install openai) y ejecuta el quickstart de la documentación:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1"
)
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."}]
)
print(completion.choices[0].message.content)
El modo thinking está activado por defecto en qwen4-max, así que esta llamada también consume tokens de razonamiento. Para prompts largos, usa streaming o establece un timeout de cliente de 180 segundos o más.
Modo thinking y streaming de reasoning_content
Qwen4-Max es un modelo híbrido de thinking. Los valores predeterminados documentados son enable_thinking=true, reasoning_effort=high y thinking_budget=131072. Los niveles de esfuerzo son low, high y xhigh; none desactiva el thinking.
Transmite el razonamiento y la respuesta en dos fases (adaptado del ejemplo de la página del modelo):
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
messages = [{"role": "user", "content": "Who are you"}]
completion = client.chat.completions.create(
model="qwen4-max",
messages=messages,
extra_body={"enable_thinking": True},
stream=True
)
for chunk in completion:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
print(delta.reasoning_content, end="", flush=True) # phase 1: thinking
if delta.content:
print(delta.content, end="", flush=True) # phase 2: answer
Tres reglas:
-
Limita la salida con
max_completion_tokens. Con el thinking activado,max_tokenssolo acepta valores de 1 a 32.768 (de lo contrario, devuelve un 400).max_completion_tokenscubre el razonamiento más la respuesta sin ese límite. -
Ajusta la profundidad con
extra_body. Pasa{"enable_thinking": True, "reasoning_effort": "xhigh"}para problemas difíciles, o"low"para los sencillos. -
Conserva el razonamiento en chats multientrada.
qwen4-maxtienepreserve_thinkingactivado por defecto, así que devuelve el razonamiento anterior en el camporeasoning_contentde cada mensaje del asistente, nunca dentro decontent.
Para omitir el thinking, pasa {"enable_thinking": False}.
Entrada de imágenes y video
Envía imágenes como partes image_url y videos como partes video_url. Esto refleja el ejemplo de visión de la documentación con el modelo establecido en qwen4-max:
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}},
{"type": "text", "text": "Describe what you see in this image"},
],
}],
)
Para video, usa {"type": "video_url", "video_url": {"url": "..."}, "fps": 2}. Los archivos locales se envían como Data URIs en Base64.
La guía de visión permite hasta 2.048 imágenes por URL de 20 MB cada una, 250 imágenes en Base64 y 64 MB por solicitud. El detalle de imagen se establece por defecto en high, lo que consume más tokens de entrada.
Function calling
Pasa un array tools como con cualquier modelo compatible con OpenAI:
tools = [{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Useful when you want to check the weather for a specific city.",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string", "description": "City or county, such as Singapore or New York."}},
"required": ["location"],
},
},
}]
completion = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)
Lee message.tool_calls, ejecuta la función, añade un mensaje tool y llama de nuevo.
En modo thinking, tool_choice solo acepta "auto" o "none"; para forzar una función, desactiva primero el thinking. Con el thinking activado, envía reasoning_content de vuelta junto con los resultados de las herramientas, o la precisión disminuirá.
Salidas estructuradas
qwen4-max admite el modo estricto de JSON Schema:
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Extract the name and age: Ana is 31."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "user_info",
"strict": True,
"schema": {
"type": "object",
"properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
"required": ["name", "age"],
"additionalProperties": False,
},
},
},
)
Con el modo más flexible {"type": "json_object"}, la palabra "JSON" debe aparecer en algún mensaje o la API rechazará la solicitud. La entrada de imágenes o videos recurre a json_object, por lo que el esquema no se aplica en las llamadas multimodales.
Caché de contexto y batch
Caché. Sin ninguna configuración, el caché implícito coincide con prefijos pero no garantiza aciertos. Para aciertos deterministas, usa el caché explícito de Qwen4: marca un bloque de contenido con "prompt_cache_breakpoint": {"mode": "explicit"} (el content del mensaje debe ser un array) y establece el TTL con extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}}. El TTL es 5m o 1h, y el prefijo en caché necesita al menos 1.024 tokens. Las lecturas cuestan 0,075 $ por millón de tokens, un 95 % menos que la entrada fresca.
Batch. La guía de batch factura la entrada y la salida al 50 % del precio en tiempo real y devuelve los resultados en un plazo de 24 horas. Para qwen4-max, Batch File se ejecuta en una región fuera de Singapur y no admite caché de contexto, así que revisa la guía de batch antes de planificar un pipeline basado en él.
La ruta compatible con Anthropic
¿Ya trabajas con el SDK de Anthropic? Cambia la URL base y la clave:
import anthropic
import os
client = anthropic.Anthropic(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic",
)
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "Who are you?"}],
thinking={"type": "disabled"},
)
print(message.content)
Este ejemplo desactiva el thinking, igual que el ejemplo de la documentación. Termina la URL base en /apps/anthropic. Añadir /v1/ produce /v1/v1/... y un error 404. El thinking también está activado por defecto aquí, y con el thinking habilitado max_tokens debe superar el presupuesto de thinking. El esfuerzo usa output_config.effort (low, high, xhigh), y las herramientas integradas web_search y web_fetch están disponibles en esta ruta.
Límites de tasa de la API de Qwen4-Max
De la página de límites de tasa:
| Región | RPM | TPM |
|---|---|---|
| Singapur | Dinámico | Niveles dinámicos: 5M, 10M, 20M |
| Fráncfort, Tokio, EE. UU. (Virginia) y otras regiones de alcance global | 30.000 | 5.000.000 |
Los límites se aplican por cuenta y por región, y también por segundo (RPS = RPM / 60), por lo que un pico de tráfico puede provocar throttling incluso por debajo del total por minuto.
La página de cuota gratuita indica que la cuota gratuita solo existe en Singapur, es por modelo (normalmente 1.000.000 de tokens), dura 90 días y requiere tener datos de pago registrados. No menciona qwen4-max, así que revisa la página de Free Tier en la consola, o lee cómo usar Qwen4-Max gratis.
Errores comunes de la API de Qwen4-Max
| Código | Qué significa | Solución |
|---|---|---|
401 InvalidApiKey
|
La clave y la URL base son de regiones distintas, o una clave del Token Plan se usó en un endpoint de pago por uso | Usa una clave creada en la misma región que la URL |
400 InvalidParameter
|
Suele ser un max_tokens fuera del rango de 1 a 32.768 con el thinking activado |
Cambia a max_completion_tokens
|
403 AllocationQuota.FreeTierOnly
|
Cuota gratuita agotada antes de configurar el pago | Añade los datos de pago en la página de Free Tier |
404 ModelNotFound
|
qwen4-max no está disponible en la región que llamaste |
Consulta los precios del modelo para esa región |
429 Throttling
|
Límite de RPM o TPM alcanzado | Espera y reintenta, o distribuye la carga a lo largo de varios segundos |
Deja que tu agente de programación pruebe la API de Qwen4-Max con Apidog CLI
Tu agente de programación escribe la integración, así que deja que también escriba la prueba de regresión. Apidog CLI le permite guardar el endpoint, almacenar la clave y ejecutar aserciones.
Configúralo una sola vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Luego dale a tu agente un solo prompt:
In Apidog project <projectId>, create an environment "Qwen Singapore" with base URL
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 and a secret
variable DASHSCOPE_API_KEY. Add POST /chat/completions with a Bearer auth header,
model qwen4-max and enable_thinking true. Create a test case asserting status 200,
a non-empty choices array, a usage object, and reasoning_content present on the
first choice's message. Run it and summarize any failures.
El agente lee cada esquema de payload antes de escribir y luego ejecuta el caso:
apidog environment create "Qwen Singapore" --project <projectId> --base-url https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
apidog cli-schema get environment-update
apidog environment update <envId> --project <projectId> --file env.json
apidog cli-schema get endpoint-create
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json
El reportero cli imprime si pasa o falla; json escribe un informe que el agente puede leer. Lleva el mismo apidog run ... -r junit a tu CI con la guía de CI/CD de Apidog CLI, y consulta Apidog CLI en Claude Code para más prompts. El plan gratuito de Apidog cubre hasta 4 usuarios.
Preguntas frecuentes
¿Cuál es el ID del modelo de la API de Qwen4-Max?
El ID estable es qwen4-max. El ID anterior qwen4-max-preview era solo para el Token Plan durante la vista previa que comenzó el 11 de noviembre de 2026.
¿Es la API de Qwen4-Max compatible con OpenAI?
Sí. Usa el SDK de OpenAI con la URL base /compatible-mode/v1 para Chat Completions y la API de Responses. También hay un endpoint compatible con Anthropic y la API de DashScope.
¿Cómo desactivo el thinking en la API de Qwen4-Max?
Pasa extra_body={"enable_thinking": False}. Perderás reasoning_content, pero la latencia y los tokens de salida disminuirán. ¿Comparando modelos? Consulta Qwen4-Max vs Qwen3.8.
¿Cuánto cuesta la API de Qwen4-Max?
1,50 $ por millón de tokens de entrada y 4,50 $ por millón de tokens de salida, con lecturas en caché a 0,075 $ por millón.
¿Puedo usar mi clave del Token Plan con la API de pago por token?
No. Las claves del Token Plan (sk-sp-) solo funcionan en token-plan.maas.qwencloudapi.com, y las claves de pago por uso solo funcionan en el dominio de su propia región.



Top comments (0)