¿Cómo conectar la API de Tencent Hunyuan Hy4? Ejecuta la primera solicitud con OpenAI SDK y estima el costo

¿Cómo conectar la API de Tencent Hunyuan Hy4? Ejecuta la primera solicitud con OpenAI SDK y estima el costo

Resumen: este artículo usa el SDK de Python de OpenAI para invocar la API de Tencent Hunyuan Hy4 en modo no streaming, completar con éxito la primera solicitud de solo texto y explicar cómo validar el resultado, estimar el costo, revisar la facturación y manejar los errores más comunes.

Respuesta directa: se puede acceder a la API de Tencent Hunyuan Hy4 mediante la interfaz compatible con OpenAI de APIYI. Solo necesitas preparar tres configuraciones para enviar la primera solicitud:

  • Clave API: créala en api.apiyi.com/token y colócala en la variable de entorno APIYI_API_KEY.
  • URL base del SDK: https://api.apiyi.com/v1.
  • ID del modelo: hy4.

El endpoint HTTP correspondiente es POST https://api.apiyi.com/v1/chat/completions. A fecha de 2026-11-21, en la tabla de precios, Hy4 cuesta por cada millón de tokens: entrada sin caché $0.85, salida $2.55 y lectura de caché $0.045. La facturación real se rige por la tabla de precios de APIYI, disponible en docs.apiyi.com/models (categoría Tencent).

La cronología es la siguiente: Tencent lanzó la versión oficial de Hy4 el 4 de noviembre y publicó los pesos el 20 de noviembre. APIYI ya tenía listado este modelo antes de que se publicaran los pesos; consulta el anuncio de disponibilidad en docs.apiyi.com/news/hy4-launch. El anuncio ya incluye un ejemplo de streaming, así que este artículo se centra solo en otros cuatro puntos: invocación no streaming, validación de resultados, verificación de facturación y diagnóstico de fallos. El anuncio menciona que Hy4 admite entrada de imágenes; este artículo solo muestra texto. Video, la API Responses y Computer Use quedan fuera del alcance de este artículo, y tampoco se incluyen datos de pruebas reales.

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-es-image-0

Mapa de conocimiento y orden de lectura para la integración de la API de Tencent Hunyuan Hy4

El flujo completo tiene cuatro pasos; la salida de cada paso es la entrada del siguiente. Se recomienda leer en el orden numerado. La sección 4 se puede consultar por separado cuando aparezca un error.

Paso Sección correspondiente Por qué está aquí Criterio de aceptación
Preparar la solicitud 1.1 y 1.2 Si el endpoint, el nombre del modelo o la clave API están mal escritos, los pasos siguientes fallarán El SDK se puede importar, la variable de entorno puede leer la clave API y no hay ninguna clave API en texto plano en el código
Primera llamada 2.1 y 2.2 Primero usar un texto corto que no contenga datos del cliente para confirmar que la conexión funciona El contenido devuelto es «产品=混元、版本=Hy4», no está truncado y se guardaron usage y request ID
Verificar la facturación 3.1 y 3.2 Una vez que la conexión funciona, estimar el costo para decidir si se puede escalar el volumen de llamadas La estimación coincide partida por partida con el registro de consumo de la consola
Diagnóstico de fallos 4 Cuando falle cualquiera de los pasos, localizar la causa según el código y el cuerpo del error Poder distinguir errores de configuración, problemas de permisos, limitación de frecuencia y tiempos de espera agotados, y determinar si se puede reintentar

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-es-image-1

Para saber: términos relacionados con la API de Hy4

Término Explicación breve
Sin streaming (stream=False) El modelo devuelve el resultado completo de una vez después de terminar la generación, lo que facilita revisar el contenido y el consumo en su conjunto
finish_reason Motivo por el que terminó esta generación. stop indica una finalización normal; length indica que se truncó al alcanzar el límite de longitud
usage Campo de consumo de tokens en la respuesta; los más comunes son prompt_tokens (entrada) y completion_tokens (salida)
request ID Identificador de una solicitud individual, que sirve para localizar esta llamada en los registros. No todas las respuestas lo incluyen necesariamente
Lectura de caché La parte de la entrada que acierta en la caché, facturada según la tarifa independiente de lectura de caché
Grupo (Default/SVIP) Grupo al que pertenece el token, que determina qué modelos puede invocar dicho token

1. Preparar la solicitud a la API de Tencent Hunyuan Hy4

1.1 Configurar el modelo Hy4 y el endpoint

Verifica cada elemento de configuración uno por uno. La mayoría de los fallos en la primera llamada ocurren justo en este paso.

Elemento de configuración Valor Descripción
SDK base_url https://api.apiyi.com/v1 Solo hasta /v1; el SDK añadirá /chat/completions automáticamente
Endpoint HTTP POST https://api.apiyi.com/v1/chat/completions Usa esta dirección cuando no utilices el SDK y envíes la solicitud HTTP directamente
ID del modelo hy4 Nombre del modelo de la versión oficial; escríbelo en minúsculas tal cual
Grupos disponibles Default, SVIP El grupo al que pertenece el token debe incluir Hy4
Modo de salida stream=False En este artículo se usa el modo no streaming en todo momento

El error más común es colocar el endpoint completo en base_url. El SDK volverá a añadir /chat/completions detrás de esa dirección, lo que duplica la ruta y termina devolviendo un 404. La documentación completa de la interfaz compatible está en docs.apiyi.com/api-capabilities/openai/compatible.

1.2 Instalar el SDK de OpenAI y guardar la Key de forma segura

La dirección del proyecto oficial del SDK de Python es github.com/openai/openai-python. Se recomienda instalarlo en un entorno virtual para evitar conflictos de versión con paquetes ya existentes en el sistema:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install openai

La Key se crea en api.apiyi.com/token. Al crearla, asegúrate de que el grupo al que pertenece el token pueda invocar Hy4. Una vez tengas la Key, guárdala en la variable de entorno del terminal actual; no la escribas en el archivo de código:

export APIYI_API_KEY="tu token"     # Windows PowerShell: $env:APIYI_API_KEY="tu token"

Al gestionar la Key, ten en cuenta los siguientes puntos:

  • El código lee la Key únicamente a través de os.environ['APIYI_API_KEY']. Si la variable de entorno no está definida, usa getpass para solicitarla de forma interactiva; lo que introduzcas no se mostrará en pantalla.
  • Si guardas la Key en un archivo .env, añádelo a .gitignore para evitar subirlo al repositorio.
  • Si la Key aparece en capturas de pantalla, logs o tickets, sustitúyela primero por una máscara como sk-***.

Verificación: ejecuta en el terminal python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))". Si se muestra el número de versión y True, significa que este paso está completado.

2. Enviar la primera solicitud a Hy4 con el SDK de OpenAI

2.1 Ejemplo completo en Python sin streaming

Esta primera solicitud hace solo algo muy simple: extraer el nombre del producto y el número de versión de una frase pública, sin incluir ningún dato de cliente. Este diseño tiene dos ventajas. Primera, la salida es muy corta y el costo bajo. Segunda, la respuesta es única, así que es fácil saber si acertó o no.

import os
import re
from getpass import getpass
from openai import OpenAI

key = os.environ.get("APIYI_API_KEY") or getpass("输入 APIYI_API_KEY:")

PROMPT = "仅从这句话提取产品和版本:腾讯混元 Hy4 正式版已上线。请只写一行:产品=…;版本=…"

with OpenAI(
    base_url="https://api.apiyi.com/v1",   # Interfaz compatible con OpenAI de APIYI
    api_key=key,
    timeout=60.0,
    max_retries=0,                         # Desactiva el reintento automático; si falla, una persona decide si reenviar
) as client:
    result = client.chat.completions.create(
        model="hy4",
        messages=[{"role": "user", "content": PROMPT}],
        stream=False,
    )

request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "响应未提供")

if not result.choices:
    raise SystemExit("未通过:choices 为空,没有返回正文")

choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)

usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 处理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 处理)")


def accept(text: str, finish_reason) -> tuple[bool, str]:
    if not text:
        return False, "正文为空"
    if finish_reason == "length":
        return False, "输出被截断"
    t = re.sub(r"\s+", "", text)
    t = t.replace(":", "=").replace(":", "=").replace(";", ";")
    prod = re.search(r"产品=([^;\n]+)", t)
    ver = re.search(r"版本=([^;\n]+)", t)
    if not prod or not ver:
        return False, "缺少产品或版本字段"
    strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
    if "混元" not in strip_punct(prod.group(1)):
        return False, f"产品值错误:{prod.group(1)}"
    if strip_punct(ver.group(1)) != "Hy4":
        return False, f"版本值错误:{ver.group(1)}"
    return True, "通过"


ok, reason = accept(content, choice.finish_reason)
print("验收:", reason)

Algunos ajustes del ejemplo merecen una explicación:

  • max_retries=0 desactiva el reintento automático del SDK. En la sección 4 veremos que, después de un timeout, el servidor puede haber ejecutado ya la solicitud, y reenviarla de forma automática podría generar un cobro duplicado; por eso, si se reintenta o no, debe decidirlo una persona.
  • La sentencia with cierra la conexión cuando termina la llamada.
  • Cuando falta el campo usage, el código imprime explícitamente «缺失» y no lo trata como 0, para que más adelante no se pierdan costos al hacer cuentas.

Para más detalles sobre la estructura de la respuesta, consulta docs.apiyi.com/api-capabilities/openai/response-handling.

2.2 Criterios de aceptación para la primera solicitud Hy4

Al validar, solo hay que fijarse en dos campos de message.content: el valor de producto debe contener “混元” y el valor de versión debe ser “Hy4”. Se aceptan diferencias entre dos puntos y punto y coma de ancho completo o medio, así como diferencias de puntuación al final de la frase. A continuación, una línea de salida que cumple los requisitos; esto es un formato ilustrativo, no una respuesta real:

产品=腾讯混元;版本=Hy4

Los siguientes casos se consideran siempre no aprobados; no se deben dar por válidos solo porque «parecen casi correctos»:

Caso Veredicto Motivo
choices está vacío, o content es una cadena vacía No aprobado No se obtuvo el cuerpo del mensaje, lo que indica que la ruta de la llamada no funcionó realmente
finish_reason es length No aprobado La salida quedó truncada; el resultado está incompleto
La versión está escrita como Hy3, Hunyuan u otro valor No aprobado El valor del campo es incorrecto
Solo cambian el ancho completo o medio de los signos de puntuación, los espacios o los dos puntos Aprobado Es una diferencia de formato permitida

Una vez aprobada la validación, registre el request ID (si aparece en la respuesta), la hora de la solicitud, el nombre del modelo, prompt_tokens y completion_tokens. Esta información será necesaria al revisar la facturación en la sección 3.2.

3. Estimar y verificar los costes de la API Hy4

3.1 Estimar una tarea por lotes con la tabla de precios

La entrada de la primera solicitud es muy corta, así que su coste resulta insignificante y usarla para estimar el gasto no tiene mucho sentido. Cambiemos a un escenario hipotético que no tiene nada que ver con aquella solicitud corta del ejemplo: supongamos una tarea con 100 000 tokens de entrada, ninguno con acierto de caché, y 20 000 tokens de salida. La entrada y la salida se calculan cada una con su propio precio unitario:

Concepto de facturación Uso supuesto Precio unitario (por millón de tokens) Coste
Entrada sin acierto de caché 100,000 $0.85 $0.085
Salida 20,000 $2.55 $0.051
Total — — $0.136

El cálculo es 0.1 × 0.85 + 0.02 × 2.55 = 0.136. A la hora de estimar hay que tener en cuenta dos cosas:

  • El precio de la salida triplica el de la entrada sin acierto de caché. En tareas con mucho volumen de salida, el coste lo determina sobre todo la salida.
  • Si completion_tokens ya incluye la parte de razonamiento del modelo, no añadas aparte un coste de razonamiento, porque lo contarías dos veces.

3.2 Distinguir el bucket de caché del registro real de consumo

La «lectura de caché» es un concepto que se factura aparte, pero la forma de desglosar los campos no tiene por qué ser la misma en todas las respuestas, así que no existe un nombre de campo universal que garantice un resultado exacto. Lo fiable es comprobar primero en la factura si los tokens con acierto de caché ya están incluidos en la entrada total.

Si la factura confirma que la parte de caché ya está dentro de la entrada total, resta esa parte de caché una vez del total de entrada y luego aplica cada precio por separado. Mantengamos el supuesto de 3.1 y añadamos que, de los 100 000 tokens de entrada, 40 000 tienen acierto de caché:

Concepto de facturación Uso supuesto Precio unitario (por millón de tokens) Coste
Entrada sin acierto de caché 60,000 $0.85 $0.051
Lectura de caché 40,000 $0.045 $0.0018
Salida 20,000 $2.55 $0.051
Total — — $0.1038

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-es-image-2

Los valores estimados solo sirven de referencia; lo que cuenta al final es el registro de consumo. Para verificarlo, filtra los registros correspondientes en la consola api.apiyi.com/log:

  1. Acota el rango por la hora de la solicitud.
  2. Si la respuesta proporciona un request ID, úsalo para localizar con precisión esa solicitud.
  3. Confirma que el modelo es hy4 y que el token coincide con el que usa realmente el código.
  4. Compara el uso de entrada, caché y salida, y el importe cobrado que aparecen en el registro, para ver si coinciden con los valores estimados.

El significado concreto de los campos del registro se explica en docs.apiyi.com/faq/log-billing-explained.

4. Resolución de problemas de fallos en la API Hy4

Al solucionar problemas, primero revisa el código de estado HTTP y luego lee la información específica del cuerpo del error. Quedarse solo con el código de estado facilita diagnósticos erróneos; por ejemplo, un 429 puede deberse a causas completamente distintas. En la solicitud original de la sección 2.1, captura las excepciones del SDK: para tiempos de espera de conexión revisa APITimeoutError, para otras fallas de conexión revisa APIConnectionError; cuando obtengas una respuesta de error, registra desde APIStatusError el status_code, el request_id y el cuerpo del error. Primero determina el resultado de la solicitud existente y luego decide si vale la pena reintentar; antes de enviar comentarios, anonimiza el cuerpo del error. El orden de procesamiento es el siguiente:

Error Verificación prioritaria ¿Reintentar?
401 Si la Key es correcta, si ya caducó, y si base_url es https://api.apiyi.com/v1 No reintentar antes de corregir la configuración
403 Según el cuerpo del error, determinar si es un problema de permisos de grupo; confirmar que el grupo del token incluya Hy4 No reintentar antes de corregir los permisos
404 Si la ruta concatenó /chat/completions de forma duplicada, y si el nombre del modelo es hy4 No reintentar antes de corregir la configuración
429 Según el cuerpo del error, determinar si es limitación temporal de tasa o cuota insuficiente La limitación temporal admite reintentos con backoff limitados; la cuota insuficiente requiere recargar o ajustar la cuota primero
Error de conexión Si la red, el proxy y el DNS funcionan correctamente, y si el protocolo y dominio de base_url son correctos Se puede reintentar tras restablecerse la red
Tiempo de espera Primero busca por hora en api.apiyi.com/log para confirmar si la solicitud ya se ejecutó Si ya se ejecutó, no reenviar; si no se ejecutó, entonces reintentar

Cabe explicar especialmente los casos de 429 y tiempo de espera:

  • Reintento con backoff para 429: solo aplica a limitación temporal de tasa. El número de reintentos debe tener un límite superior, y el intervalo debe aumentar gradualmente en cada intento. Cuando la cuota es insuficiente, por muchos reintentos que hagas, nunca tendrán éxito.
  • Tiempo de espera: que el cliente no reciba respuesta en 60 segundos no significa que el servidor no haya procesado la solicitud. Si el servidor ya terminó de procesarla, reenviarla directamente la ejecutará de nuevo, y también se cobrará otra vez. Por eso, primero revisa los logs, confirma que la solicitud no se ejecutó, y luego reenvíala.

Si necesitas contactar al soporte técnico, antes de enviar anonimiza la Key, los datos del cliente y demás información sensible en el cuerpo del error y los logs, y luego adjunta el código de estado, la hora de la solicitud, el nombre del modelo y el request ID. Para saber cómo conservar y enviar la información de error, consulta docs.apiyi.com/api-manual/error-reporting.

Una vez completada toda la resolución de problemas, vuelve a ejecutar el ejemplo de 2.1. Todo el flujo solo se considera aprobado si cumple las tres condiciones siguientes al mismo tiempo:

  1. La función de aceptación imprime «通过».
  2. finish_reason no es length.
  3. En los logs de la consola se puede encontrar un registro con la misma hora y el modelo hy4, y el uso coincide con el usage registrado localmente.

Publicaciones Similares