Como integrar a API Tencent Hunyuan Hy4? Use o OpenAI SDK para executar a primeira solicitação e estimar os custos

Como integrar a API Tencent Hunyuan Hy4? Use o OpenAI SDK para executar a primeira solicitação e estimar os custos

Resumo: Este artigo usa o SDK Python da OpenAI para chamar a API do Tencent Hunyuan Hy4 de forma não streaming, conclui a primeira requisição de texto puro e explica como validar o resultado, estimar custos, conferir a fatura e lidar com erros comuns.

Resposta direta: A API do Tencent Hunyuan Hy4 pode ser acessada pela interface compatível com OpenAI da APIYI. Basta preparar três configurações para enviar a primeira requisição:

  • Key: Crie em api.apiyi.com/token e coloque na variável de ambiente APIYI_API_KEY.
  • SDK Base URL: https://api.apiyi.com/v1.
  • ID do modelo: hy4.

O endpoint HTTP correspondente é POST https://api.apiyi.com/v1/chat/completions. Em 21/11/2026, os preços do Hy4 na tabela de preços por milhão de tokens são: entrada sem cache hit $0.85, saída $2.55, leitura de cache $0.045. O faturamento real segue a tabela de preços da APIYI, em docs.apiyi.com/models (categoria Tencent).

A linha do tempo é a seguinte: a Tencent lançou a versão oficial do Hy4 em 4 de novembro e abriu os pesos em 20 de novembro. A APIYI já disponibilizou o modelo antes da abertura dos pesos; o anúncio de lançamento está em docs.apiyi.com/news/hy4-launch. O anúncio já traz um exemplo de streaming, então este artigo cobre apenas outras quatro coisas: chamada não streaming, validação de resultados, conferência de fatura e solução de falhas. O anúncio menciona que o Hy4 aceita entrada de imagens, mas este artigo demonstra apenas texto puro. Vídeo, a interface Responses e o Computer Use estão fora do escopo deste artigo, e o texto não contém nenhum dado de teste real.

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

Mapa de conhecimento e ordem de leitura para a integração da API do Tencent Hunyuan Hy4

O fluxo todo tem quatro etapas, e o resultado de cada uma vira a entrada da próxima. Recomendo ler na ordem dos números. A seção 4 pode ser consultada à parte quando aparecer um erro.

Etapa Seção correspondente Por que fica aqui Critério de aceite
Preparar a requisição 1.1, 1.2 Se o endpoint, o nome do modelo e a Key estiverem errados, todas as etapas seguintes falham O SDK importa, as variáveis de ambiente conseguem ler a Key e não existe Key em texto claro no código
Primeira invocação 2.1, 2.2 Primeiro use um texto curto, sem dados de cliente, só para confirmar que o caminho está funcionando O conteúdo retornado é “产品=混元、版本=Hy4”, sem truncamento, e o usage e o request ID foram salvos
Conferir o consumo 3.1, 3.2 Só depois de o caminho estar funcionando, estimar o custo para decidir se dá para aumentar o volume de chamadas Os valores estimados batem item por item com o log de consumo do console
Diagnóstico de falhas 4 Quando qualquer etapa falhar, localizar a causa pelo código e pelo corpo do erro Conseguir distinguir erro de configuração, problema de permissão, rate limit e timeout, e julgar se vale tentar de novo

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

To Know: termos relacionados à API Hy4

Termo Explicação resumida
Não-streaming (stream=False) O modelo retorna o resultado completo de uma vez só, depois de terminar a geração, o que facilita conferir o conteúdo e o consumo como um todo
finish_reason O motivo do fim desta geração. stop indica término normal; length indica que atingiu o limite de comprimento e foi truncado
usage Campo de consumo de tokens na resposta; os mais comuns são prompt_tokens (entrada) e completion_tokens (saída)
request ID O identificador de uma requisição, usado para localizar essa chamada nos logs. Não vem necessariamente em toda resposta
Leitura de cache A parte da entrada que acerta o cache, cobrada pelo preço específico de leitura de cache
Grupo (Default/SVIP) O grupo ao qual o token pertence, que define quais modelos esse token pode chamar

1. Preparar a requisição da API Tencent Hunyuan Hy4

1.1 Configurar o modelo Hy4 e o endpoint

Confira cada item de configuração com cuidado. A maioria das falhas na primeira invocação acontece nesta etapa.

Item de configuração Valor Descrição
base_url do SDK https://api.apiyi.com/v1 Preencha apenas até /v1; o SDK acrescenta /chat/completions automaticamente
Endpoint HTTP POST https://api.apiyi.com/v1/chat/completions Use este endereço ao enviar a requisição HTTP diretamente, sem o SDK
ID do modelo hy4 Nome do modelo da versão oficial; preencha exatamente em minúsculas
Grupos disponíveis Default, SVIP O grupo ao qual o token pertence precisa incluir o Hy4
Modo de saída stream=False Este artigo usa o modo não-streaming durante todo o texto

O erro mais comum é colocar o endpoint completo no base_url. O SDK acrescenta /chat/completions de novo após esse endereço, causando duplicação do caminho e, por fim, retornando 404. A documentação completa da interface compatível está em docs.apiyi.com/api-capabilities/openai/compatible.

1.2 Instalar o OpenAI SDK e salvar a Key com segurança

O endereço do projeto oficial do Python SDK é github.com/openai/openai-python. Recomenda-se instalar em um ambiente virtual para evitar conflito de versões com pacotes já presentes no sistema:

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

A Key é criada em api.apiyi.com/token. Ao criar, confirme que o grupo ao qual o token pertence pode invocar o Hy4. Depois de obter a Key, escreva-a na variável de ambiente do terminal atual; não a coloque no código:

export APIYI_API_KEY="你的令牌"     # Windows PowerShell: $env:APIYI_API_KEY="你的令牌"

Ao administrar a Key, observe os pontos a seguir:

  • O código lê a Key apenas via os.environ['APIYI_API_KEY']. Quando a variável de ambiente não está definida, faça a entrada interativa com getpass; o conteúdo digitado não aparece na tela.
  • Se salvar a Key em um arquivo .env, adicione-o ao .gitignore para evitar que seja commitado no repositório.
  • Se a Key aparecer em capturas de tela, logs ou tickets, substitua primeiro por uma máscara como sk-***.

Verificação: execute no terminal python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))". Se aparecer o número da versão e True, esta etapa está concluída.

2. Enviando a primeira requisição Hy4 com o SDK da OpenAI

2.1 Exemplo completo em Python sem streaming

Esta primeira requisição faz apenas uma coisa simples: extrair o nome do produto e o número da versão de uma frase pública, sem nenhum dado de cliente. Essa escolha de design traz dois benefícios. Primeiro, a saída é bem curta, então o custo é baixo. Segundo, a resposta é única, o que facilita verificar se está certa ou errada.

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",   # Interface compatível com OpenAI da APIYI
    api_key=key,
    timeout=60.0,
    max_retries=0,                         # Desativa a repetição automática; em caso de falha, uma pessoa decide se deve 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)

Alguns ajustes do exemplo merecem explicação:

  • max_retries=0 desativa a repetição automática do SDK. Como veremos na seção 4, após um timeout o servidor pode já ter concluído a requisição; reenviar automaticamente pode gerar cobrança duplicada, então quem decide se deve ou não tentar de novo é uma pessoa.
  • A instrução with fecha a conexão ao final da chamada.
  • Quando o campo usage está ausente, o código imprime explicitamente “缺失” em vez de tratar como 0, evitando deixar custos de fora numa eventual conferência de gastos.

Mais detalhes sobre a estrutura da resposta estão em docs.apiyi.com/api-capabilities/openai/response-handling.

2.2 Critérios de aceitação para a primeira requisição Hy4

Na verificação, olhamos apenas para dois campos em message.content: o valor do produto deve conter “混元” e o valor da versão deve ser “Hy4”. Diferenças de dois-pontos e ponto e vírgula em largura total ou meia largura, assim como de pontuação no fim da frase, são aceitáveis. Abaixo está uma linha de saída que atende aos requisitos, este é um formato ilustrativo, não é um retorno real de teste:

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

As situações a seguir são sempre reprovadas — não dá para aprovar só porque “parece quase igual”:

Situação Veredito Motivo
choices vazio, ou content como string vazia Reprovado Não obtivemos o texto, o que indica que o fluxo não funcionou de fato
finish_reason igual a length Reprovado A saída foi truncada, o resultado está incompleto
Versão escrita como Hy3, Hunyuan ou outro valor Reprovado Valor do campo incorreto
Diferença apenas na largura total/meia largura de pontuação, espaço ou dois-pontos Aprovado É uma diferença de formato permitida

Depois que a verificação passar, registre o request ID (se houver na resposta), o horário da requisição, o nome do modelo, prompt_tokens e completion_tokens. Essas informações serão usadas na seção 3.2 para conferir a fatura.

3. Estimar e verificar os custos da API Hy4

3.1 Estimar uma tarefa em lote pela tabela de preços

A entrada da primeira requisição é bem curta e o custo é desprezível — usá-la para estimar custos faz pouco sentido. A seguir, trocamos por um cenário hipotético sem relação com aquela requisição curta de exemplo: suponha uma tarefa com 100 mil tokens de entrada, todos sem acerto de cache, e 20 mil tokens de saída. Entrada e saída são calculadas com seus respectivos preços unitários:

Item de cobrança Uso hipotético Preço unitário (por milhão de tokens) Custo
Entrada sem acerto de cache 100.000 $0,85 $0,085
Saída 20.000 $2,55 $0,051
Total — — $0,136

O cálculo é 0,1 × 0,85 + 0,02 × 2,55 = 0,136. Ao estimar, dois pontos merecem atenção:

  • O preço da saída é 3 vezes o da entrada sem acerto de cache. Em tarefas com muito volume de saída, o custo é dominado pela saída.
  • Se completion_tokens já inclui a parte de raciocínio do modelo, não acrescente uma cobrança separada de raciocínio, senão você conta duas vezes.

3.2 Distinguir o balde de cache dos logs de consumo reais

“Leitura de cache” é um item de cobrança separado, mas a forma de dividir os campos varia entre as respostas, então não existe um nome de campo universal que garanta precisão. O caminho confiável é primeiro confirmar na fatura: os tokens que acertaram o cache já estão contados dentro da entrada total?

Se a fatura confirmar que a parte de cache já está incluída na entrada total, subtraia uma vez a parte de cache da entrada total e então aplique os preços separadamente. Vamos manter o cenário hipotético de 3.1 e supor ainda que, dos 100 mil tokens de entrada, 40 mil acertaram o cache:

Item de cobrança Uso hipotético Preço unitário (por milhão de tokens) Custo
Entrada sem acerto de cache 60.000 $0,85 $0,051
Leitura de cache 40.000 $0,045 $0,0018
Saída 20.000 $2,55 $0,051
Total — — $0,1038

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

Os valores estimados servem apenas como referência — o que vale no fim é o log de consumo. Para conferir, filtre os registros correspondentes no console em api.apiyi.com/log:

  1. Reduza o intervalo pela hora da requisição.
  2. Se a resposta trouxer um request ID, use-o para localizar exatamente aquela requisição.
  3. Confirme que o modelo é hy4 e que o token usado é o mesmo que o código realmente utiliza.
  4. Compare com os valores estimados os usos de entrada, cache e saída e o valor cobrado no log, para ver se batem.

O significado detalhado dos campos do log está em docs.apiyi.com/faq/log-billing-explained.

4. Solução de problemas de falha da API Hy4

Ao solucionar problemas, primeiro observe o código de status HTTP e depois leia as informações específicas no corpo do erro. Olhar apenas o código de status facilita um diagnóstico equivocado: por exemplo, dois erros 429 podem ter causas completamente diferentes. Na requisição original da seção 2.1, capture as exceções do SDK: para timeout de conexão, verifique APITimeoutError; para outras falhas de conexão, verifique APIConnectionError; ao receber uma resposta de erro, registre a partir de APIStatusError o status_code, o request_id e o corpo do erro. Primeiro avalie o resultado da requisição existente e só depois decida se deve tentar novamente; antes de enviar um feedback, anonimize o corpo do erro. A ordem de tratamento é a seguinte:

Erro Verificação prioritária Tentar novamente?
401 Se a Key está correta, se já expirou e se o base_url é https://api.apiyi.com/v1 Não tente novamente antes de corrigir a configuração
403 Com base no corpo do erro, verifique se é um problema de permissão de grupo e confirme se o grupo ao qual o token pertence inclui o Hy4 Não tente novamente antes de corrigir as permissões
404 Se o caminho está com /chat/completions concatenado repetidamente e se o nome do modelo é hy4 Não tente novamente antes de corrigir a configuração
429 Com base no corpo do erro, determine se é limitação temporária de taxa ou cota insuficiente Para limitação temporária, é possível tentar novamente com backoff por um número limitado de vezes; para cota insuficiente, é preciso primeiro recarregar ou ajustar a cota
Erro de conexão Se a rede, o proxy e o DNS estão normais, e se o protocolo e o domínio do base_url estão corretos É possível tentar novamente após a rede se recuperar
Timeout Primeiro procure em api.apiyi.com/log pelo horário e confirme se a requisição já foi executada Se já foi executada, não reenvie; se não foi executada, tente novamente

É preciso explicar especialmente os casos de 429 e timeout:

  • Retentativa com backoff para 429: aplica-se apenas à limitação temporária de taxa. O número de tentativas deve ter um limite máximo, com o intervalo aumentando gradualmente a cada tentativa. Quando a cota é insuficiente, não importa quantas vezes você tente, nunca dará certo.
  • Timeout: o fato de o cliente não receber resposta em 60 segundos não significa que o servidor não processou a requisição. Se o servidor já terminou o processamento, reenviar diretamente fará com que seja executado mais uma vez, e a cobrança será feita novamente. Portanto, primeiro consulte os logs, confirme que a requisição não foi executada e só então reenvie.

Se precisar entrar em contato com o suporte técnico, antes de enviar, anonimize as informações sensíveis no corpo do erro e nos logs, como a Key e os dados do cliente, e anexe o código de status, o horário da requisição, o nome do modelo e o request ID. Para saber como armazenar e enviar informações de erro, consulte docs.apiyi.com/api-manual/error-reporting.

Depois de concluir toda a solução de problemas, execute novamente o exemplo da seção 2.1. O fluxo completo só é considerado aprovado se atender simultaneamente a três condições:

  1. A função de validação exibe “通过”.
  2. O finish_reason não é length.
  3. Nos logs do console é possível encontrar um registro no mesmo horário, com o modelo hy4, e o uso deve ser consistente com o usage registrado localmente.

Similar Posts