
Cómo usar Qwen3.8 Max: Python, TypeScript y cURL
qwen3.8-max para Chat Completions, Responses y Messages. La URL de documentación conserva el slug Preview histórico; usa el ID de producción y ejecuta un smoke test en tu cuenta antes de enviar tráfico.Lanzamiento QwenCloud y estado EvoLink
| Superficie | ID | Estado |
|---|---|---|
| QwenCloud | qwen3.8-max | Flagship upstream oficial |
| Token Plan | qwen3.8-max-preview | Canal Preview |
| EvoLink | qwen3.8-max | Ruta de producción disponible; la URL de documentación conserva el slug Preview |
Antes de la primera solicitud
| Requisito | Preparación | Motivo |
|---|---|---|
| Clave EvoLink | Crear en el panel de API Keys | Autenticación Bearer |
| Base URL | https://direct.evolink.ai/v1 para texto | Separa SDK y endpoint |
| URL multimodal | https://api.evolink.ai/v1 para imagen, audio o vídeo | Endpoint multimodal documentado |
| Variable de modelo | ID exacto de EvoLink | Cambia Preview por GA sin tocar código |
| Smoke test | Una solicitud breve | Comprueba auth, ruta, respuesta y facturación |
| Fallback | Modelo ya verificado | Mantiene el servicio ante cambios |
export EVOLINK_API_KEY="your-evolink-api-key"
export EVOLINK_BASE_URL="https://direct.evolink.ai/v1"
export EVOLINK_QWEN_MODEL="qwen3.8-max-preview"Árbol de decisión del protocolo
Usa Chat para aplicaciones OpenAI existentes, Responses para agentes nuevos con herramientas o estado, y Messages para stacks Anthropic.
Existing OpenAI-compatible chat application?
├─ Yes → Chat Completions
└─ No
├─ New agent needs built-in tools or server-linked turns? → Responses
└─ Existing Anthropic Messages stack? → MessagesSustituye el último valor por el ID exacto de EvoLink; no presupongas que será idéntico al ID upstream.
Elegir Chat, Responses o Messages
| Protocolo | Endpoint | Mejor uso | Diferencia |
|---|---|---|---|
| Chat Completions | /v1/chat/completions | Chats OpenAI existentes | messages; thinking en reasoning_content |
| Responses | /v1/responses | Agentes, herramientas y turnos enlazados | input, previous_response_id, caché |
| Messages | /v1/messages | SDK Anthropic | system superior y max_tokens obligatorio |
Empieza por Chat para OpenAI, Responses para tools o estado servidor, y Messages para bloques y eventos Anthropic.
Primera llamada con cURL
curl --request POST \
--url "${EVOLINK_BASE_URL}/chat/completions" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"messages\": [
{
\"role\": \"system\",
\"content\": \"You are a concise software architecture assistant.\"
},
{
\"role\": \"user\",
\"content\": \"Return three checks for a safe API rollout.\"
}
]
}"id, model, al menos un choices y usage. Guarda el modelo devuelto como evidencia de resolución del alias.Python con OpenAI SDK
pip install openaiimport os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["EVOLINK_QWEN_MODEL"],
messages=[
{
"role": "system",
"content": "You are a concise software architecture assistant.",
},
{
"role": "user",
"content": "Return three checks for a safe API rollout.",
},
],
)
print(response.choices[0].message.content)
print(response.model)Clave, Base URL e ID son la frontera de integración. Cambia configuración antes de modificar prompts o lógica.
TypeScript
npm install openaiimport OpenAI from "openai";
const apiKey = process.env.EVOLINK_API_KEY;
const model = process.env.EVOLINK_QWEN_MODEL;
if (!apiKey || !model) {
throw new Error("EVOLINK_API_KEY and EVOLINK_QWEN_MODEL are required");
}
const client = new OpenAI({
apiKey,
baseURL: process.env.EVOLINK_BASE_URL ?? "https://direct.evolink.ai/v1",
});
const response = await client.chat.completions.create({
model,
messages: [
{
role: "system",
content: "You are a concise software architecture assistant.",
},
{
role: "user",
content: "Return three checks for a safe API rollout.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.model);Separa Thinking y contenido final en streaming
reasoning_content y content por separado.import os
from openai import OpenAI
model = os.environ.get("EVOLINK_QWEN_MODEL")
if not model:
raise RuntimeError("EVOLINK_QWEN_MODEL is required")
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
stream = client.chat.completions.create(
model=model,
messages=[
{"role": "user", "content": "Review this rollout plan for failure modes."}
],
stream=True,
extra_body={"enable_thinking": True},
)
for chunk in stream:
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
print(reasoning, end="", flush=True)
if delta.content:
print(delta.content, end="", flush=True)EVOLINK_QWEN_MODEL al arrancar; un fallback silencioso impide auditar rollout y rollback.Responses para herramientas y estado multivuelta
input; EvoLink también documenta previous_response_id y x-dashscope-session-cache: enable.curl --request POST \
--url "${EVOLINK_BASE_URL}/responses" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--header "x-dashscope-session-cache: enable" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"input\": \"List the production checks for a model-route canary.\"
}"Responses: segundo turno y Session Cache
previous_response_id. El header no demuestra un hit; revisa usage.curl --request POST \
--url "${EVOLINK_BASE_URL}/responses" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--header "x-dashscope-session-cache: enable" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"previous_response_id\": \"resp_FROM_FIRST_CALL\",
\"input\": \"Turn those checks into a five-step canary plan.\"
}"id solo si privacidad y retención permiten conversaciones enlazadas. La documentación actual indica siete días de validez; revísalo para flujos duraderos.Messages para stacks Anthropic
messages y exige max_tokens.curl --request POST \
--url "${EVOLINK_BASE_URL}/messages" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"max_tokens\": 1024,
\"system\": \"You are a concise software architecture assistant.\",
\"messages\": [
{
\"role\": \"user\",
\"content\": \"Return three checks for a safe API rollout.\"
}
]
}"Validación de tools, reintentos limitados y fallback
Los argumentos son entrada no fiable: valida nombre, schema, autorización y entorno antes de efectos.
import { z } from "zod";
const createCanarySchema = z.object({
workload: z.string().min(1).max(80),
trafficPercent: z.number().min(0.1).max(10),
});
function validateToolCall(name: string, rawArguments: string) {
if (name !== "create_canary") {
throw new Error(`Blocked unknown tool: ${name}`);
}
return createCanarySchema.parse(JSON.parse(rawArguments));
}Reintenta solo timeout, conexión, 429 y 5xx transitorios con límites; no repitas 400/401/402 sin cambios.
import os
import random
import time
from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
def complete_with_fallback(messages):
models = [
os.environ["EVOLINK_QWEN_MODEL"],
os.environ["EVOLINK_FALLBACK_MODEL"],
]
for model in models:
for attempt in range(3):
try:
return client.chat.completions.create(
model=model,
messages=messages,
timeout=60,
)
except APIStatusError as error:
if error.status_code != 429 and error.status_code < 500:
raise
except (APIConnectionError, APITimeoutError):
pass
time.sleep((2 ** attempt) + random.random())
raise RuntimeError("Primary and fallback routes failed")Registro de validación en producción
| Capacidad | Estado de la ruta | Evidencia en tu cuenta |
|---|---|---|
| Chat / Responses / Messages | Disponible; validar | ID, modelo, HTTP, stop y usage |
| Streaming / Thinking | Disponible; validar | Primer evento, final, razonamiento y contenido |
| Tools / Cache / Multimodal | Validar en el endpoint objetivo | Argumentos, continuación, usage de caché y formatos |
system superior, content blocks, caché y eventos Anthropic; no conviertas Chat mecánicamente.
Activar funciones de forma controlada
| Función | Chat | Responses | Messages | Control |
|---|---|---|---|---|
| Thinking | enable_thinking; reasoning_content | reasoning.effort | bloques thinking | Calidad, latencia y tokens |
| Streaming | stream: true; SSE | eventos Responses | eventos Anthropic | Cortes y salida parcial |
| Tools | funciones en tools | tools integradas y custom | bloques tool | Validar argumentos |
| Caché | cache_control | header de sesión | bloques cache_control | Revisar usage |
| Multimodal | https://api.evolink.ai/v1 | URL multimodal | bloques de imagen | Probar formato y tamaño |
No copies precios o descuentos de QwenCloud: son otro canal. Usa el precio en vivo de la página del producto EvoLink.
Solución de problemas
| Síntoma | Causa | Acción |
|---|---|---|
400 | Formato o campo incorrecto | Volver al ejemplo mínimo |
401 | Token inválido | Revisar clave y header |
402 | Créditos insuficientes | Revisar saldo |
404 | Ruta, ID o endpoint | Copiar ID exacto y verificar path |
429 | Rate limit | Backoff con jitter, menos concurrencia |
5xx | Fallo transitorio | Reintentos limitados y fallback |
| Texto vacío con thinking | Campo equivocado | Leer reasoning y salida final |
No reintentes 400, 401 o 402 sin corregirlos. Limita los reintentos de 429 y 5xx.
Checklist de producción
- Copia el ID exacto en
EVOLINK_QWEN_MODEL. - Ejecuta una solicitud breve sin streaming y guarda modelo y usage.
- Prueba streaming, tools, thinking, caché y multimodal por separado.
- Reproduce 20–50 tareas contra la base actual.
- Mide éxito, latencia aceptada, reintentos, tokens y corrección humana.
- Empieza con shadow traffic y después un canary pequeño.
- Mantén un fallback verificado en el mismo gateway.
- Revierte al cruzar límites de error, latencia, coste o calidad.
Verifica la ruta antes de la primera llamada de producción
No te registres solo por el anuncio. Resuelve primero estas preguntas y crea una clave API únicamente si la ruta encaja con tu carga.
- 01
¿Se lanzó?
Sí. Qwen3.8 Max es el modelo de producción; Preview queda como contexto histórico.
- 02
¿Está disponible?
Sí, en EvoLink. Confirma la ruta activa y el ID en la página del producto.
- 03
¿Me conviene?
Para razonamiento de contexto largo, repositorios grandes y agentes con herramientas; las tareas simples deben usar una ruta menor.
- 04
¿Cuánto cuesta?
Consulta el módulo de precios en vivo del producto; no reutilices precios upstream o del plan Preview.
- 05
¿Cómo se llama?
Elige Chat Completions, Responses o Messages y sigue la guía de integración y la referencia de parámetros.
¿Completaste las cinco comprobaciones? Crear una clave API.
Preguntas frecuentes
¿Ya se puede llamar mediante EvoLink?
La ruta sigue activándose el 3 de agosto de 2026. Espera a verla en la cuenta y completar un smoke test antes de producción.
¿Qué ID debo usar?
qwen3.8-max y la documentación actual de EvoLink qwen3.8-max-preview; mantenlo configurable.¿Qué Base URL debo usar?
https://direct.evolink.ai/v1 para texto y conexiones largas; https://api.evolink.ai/v1 para imagen, audio o vídeo.¿Chat o Responses?
Chat para aplicaciones OpenAI existentes; Responses para turnos enlazados, tools y eventos Responses.
¿Puedo usar Anthropic?
/v1/messages, conservando system, max_tokens, bloques y eventos Anthropic.¿Incluye precios?
No. El precio pertenece a la página del modelo para evitar duplicados obsoletos y canibalización.
¿Cómo manejo rate limits?
Limita concurrencia, usa backoff con jitter para 429, limita reintentos y conserva fallback.
¿Qué pruebo antes de producción?
Auth, modelo, parsing, streaming, tools, thinking, caché, multimodal, timeout, retries, billing, fallback, shadow y canary.


