Comment utiliser l'API d'aperçu Hy3 gratuitement ?

Tencent a mis en open source Hy3 Preview le 22 avril 2026, et en moins d'un jour, OpenRouter l'a listé comme un point d'accès entièrement gratuit. Pas de carte de crédit, pas de facturation de jetons, pas de période d'essai. Vous pouvez appeler le même modèle Mixture-of-Experts de 295 milliards de paramètres qui alimente l'application Yuanbao et l'assistant CodeBuddy de Tencent depuis votre propre code, aujourd'hui, pour zéro dollar.

Ce guide montre comment utiliser l'API Hy3 Preview gratuitement via OpenRouter, l'espace Hugging Face et le dépôt Hy3 brut. Il couvre également les modes de raisonnement qui distinguent Hy3 de la plupart des modèles open source de 2026, et comment tester l'API dans Apidog sans écrire de scripts jetables.

Si vous voulez le moyen le plus rapide d'obtenir votre première réponse, passez à « Étape par étape : appeler Hy3 Preview gratuitement sur OpenRouter ».

TL;DR

• Hy3 Preview est gratuit sur OpenRouter sous l'ID de modèle tencent/hy3-preview:free avec une tarification d'entrée et de sortie de 0 $.
• C'est un modèle Mixture-of-Experts : 295 milliards de paramètres au total, 21 milliards actifs, 192 experts avec routage top-8, et une fenêtre de contexte de 256K jetons.
• Trois modes de raisonnement sont intégrés : no_think pour des réponses rapides, low et high pour une chaîne de pensée approfondie sur les tâches d'agent et de codage.
• Les benchmarks sont solides pour un modèle à poids ouverts : SWE-bench Verified 74.4, Terminal-Bench 2.0 54.4, GPQA Diamond 87.2, MMLU 87.42.
• Vous pouvez l'exécuter de trois manières gratuites : le niveau gratuit d'OpenRouter, l'espace Hy3-preview de Hugging Face, ou l'inférence locale avec vLLM et les poids ouverts.
• Apidog s'accorde bien avec le point d'accès OpenRouter car Hy3 utilise le schéma OpenAI Chat Completions ; dirigez une requête vers OpenRouter et c'est parti.

Qu'est-ce que Hy3 Preview ?

Hy3 Preview est la première version phare de l'équipe restructurée de modèles fondamentaux Hunyuan de Tencent, désormais dirigée par Yao Shunyu, un ancien chercheur d'OpenAI que la société a embauché pour faire progresser sa pile de raisonnement. On peut le considérer comme le modèle le plus performant de Tencent à ce jour et une réponse directe aux meilleures versions chinoises à poids ouverts de DeepSeek, Alibaba et Zhipu.

Le profil technique de la fiche de modèle officielle est axé sur l'agent :

• Architecture : Mixture-of-Experts, 80 couches plus une couche MTP, 64 têtes d'attention avec attention à requête groupée.
• Paramètres : 295 milliards au total, 21 milliards actifs par passage avant.
• Experts : 192 spécialistes avec routage top-8 par jeton.
• Contexte : 256K jetons (262 144 sur la liste d'OpenRouter).
• Tokeniseur : Vocabulaire de 120 832 entrées avec précision BF16.
• Licence : Licence communautaire Tencent Hy, utilisation commerciale autorisée selon les termes de la licence.

Ce qui le distingue d'un MoE générique de l'ordre de 200 milliards, c'est l'entraînement agentique. Tencent a reconstruit son infrastructure RL pour l'utilisation d'outils multi-tours, et les scores publiés sur SWE-bench Verified, Terminal-Bench 2.0 et la suite interne WildClawBench le placent près des meilleurs modèles fermés sur les tâches de code et de shell.

Trois façons gratuites d'utiliser Hy3 Preview

Vous avez trois voies selon que vous souhaitez une interface de chat, une API ou des poids locaux.

La plupart des développeurs préféreront la voie OpenRouter. C'est le chemin le plus court entre l'inscription et un appel API fonctionnel, et les limites de débit du niveau gratuit sont suffisamment généreuses pour le prototypage.

Étape par étape : appeler Hy3 Preview gratuitement sur OpenRouter

Voici le chemin minimal pour obtenir une réponse `tencent/hy3-preview:free` fonctionnelle, à partir de zéro.

1. Créer un compte OpenRouter. Inscrivez-vous sur openrouter.ai. L'e-mail suffit ; aucune méthode de paiement n'est requise pour les modèles de niveau gratuit.
2. Générer une clé API. Dans le tableau de bord OpenRouter, ouvrez « Clés » et créez une nouvelle clé. Copiez-la dans une variable d'environnement, par exemple export OPENROUTER_API_KEY=sk-or-....
3. Ouvrir la page du modèle. Allez à la liste gratuite de Hy3 Preview et confirmez que la bannière d'état indique « Gratuit ». Vous y verrez également des statistiques d'utilisation ; au lancement, le point d'accès traitait 6,81 milliards de jetons de prompt par jour pour tous les utilisateurs.

Envoyer votre première requête. OpenRouter expose le schéma OpenAI Chat Completions, donc n'importe quel SDK OpenAI fonctionne :

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tencent/hy3-preview:free",
    "messages": [
      {"role": "user", "content": "Explain the MoE routing decision inside a top-8 of 192 setup in 3 sentences."}
    ],
    "temperature": 0.9,
    "top_p": 1.0
  }'

1. Activer le raisonnement quand vous en avez besoin. Hy3 accepte un paramètre reasoning avec effort défini sur low ou high. OpenRouter renvoie la trace de pensée dans un tableau reasoning_details séparé, facturé comme son propre seau de jetons :

{
  "model": "tencent/hy3-preview:free",
  "messages": [
    {"role": "user", "content": "Plan, then write a Bash script that rotates daily log files older than 30 days into a dated archive folder."}
  ],
  "reasoning": {"effort": "high"}
}

1. Itérer. Gardez la session dans le même thread si vous voulez que le modèle s'appuie sur le contexte précédent ; la fenêtre de 256K de Hy3 gère la plupart des bases de code complètes de bout en bout.

Voilà tout le processus. Le modèle que vous appelez est le même que celui publié sur Hugging Face ; la qualité sur le niveau gratuit d'OpenRouter est identique à celle des voies payantes chez d'autres fournisseurs.

Gratuit, Plus et auto-hébergé : leurs différences

Le gratuit n'est pas la seule voie, et il est utile de voir les vraies différences avant de s'engager.

Le gratuit est le bon choix pour les prototypes, les projets secondaires, les benchmarks d'évaluation et les agents à faible trafic. Le payant ou l'auto-hébergement prend tout son sens dès que la latence est importante ou que vous dépassez le plafond de débit.

Conseils de prompt et de paramètres pour tirer le meilleur parti de Hy3

Hy3 récompense une configuration explicite plus que les modèles plus petits. Quelques habitudes aident.

• Adapter la température au mode. La fiche du modèle recommande temperature=0.9 et top_p=1.0 par défaut. Descendez à 0.3 pour une sortie structurée, restez à 0.9 pour un travail créatif.
• Utiliser no_think pour le chat quotidien. Le mode de raisonnement par défaut est désactivé pour une raison ; vous n'avez besoin de low ou high que pour la planification, le code multi-étapes ou les maths. Exécuter high sur une question d'une ligne gaspille des jetons de raisonnement.
• Nommer les outils dans le prompt système. Hy3 a été entraîné pour l'utilisation d'outils avec un parseur spécifique (hy_v3). Même sur OpenRouter, vous obtenez de meilleurs appels lorsque le prompt système décrit le rôle de chaque outil au lieu de vous fier uniquement au schéma.
• Citer le code, ne pas le résumer. La fenêtre de 256K vous permet de coller des fichiers entiers. Collez le fichier, puis posez la question ; ne demandez pas au modèle d'imaginer le code.
• Traiter les modifications multi-fichiers par lots. Le score SWE-bench Verified de Hy3 de 74,4 provient de la modification cohérente de plusieurs fichiers. Donnez-lui l'ensemble complet dans un seul message plutôt que de les introduire un par un.
• Demander un plan d'abord. Pour les tâches agentiques, un schéma en deux étapes (« rédigez un plan, attendez ma confirmation, puis exécutez ») produit systématiquement des résultats plus propres que les prompts à tir unique.

Limites à connaître avant de déployer

Quelques pièges vous attendent si vous les ignorez.

• Les limites de débit varient avec la charge. Le niveau gratuit d'OpenRouter partage sa capacité entre tous les utilisateurs gratuits. Au lancement, le volume quotidien de prompts était déjà de 6,81 milliards de jetons ; les appels aux heures de pointe peuvent rencontrer des erreurs 429. Mettez en place des tentatives avec un délai d'attente exponentiel.
• Les jetons de raisonnement comptent comme sortie. Les reasoning_details sont gratuits sur le niveau gratuit d'OpenRouter, mais sur les routes payantes, ils sont facturés comme sortie. Ne déployez pas de effort: "high" par défaut dans un produit sensible aux revenus sans mesurer.
• La licence n'est pas Apache 2.0. La licence communautaire Tencent Hy permet une utilisation commerciale mais comporte des clauses de politique d'utilisation et d'attribution ; lisez la licence complète sur le dépôt GitHub avant d'intégrer Hy3 dans un produit.
• L'appel d'outils nécessite le bon parseur. Si vous auto-hébergez, exécutez vLLM ou SGLang avec --tool-call-parser hy_v3 (ou hunyuan pour SGLang). Sans cela, les appels d'outils reviennent en texte brut.
• L'anglais et le chinois sont de première classe ; les autres langues sont de seconde. Les scores C-Eval 89.80 et CMMLU 89.61 montrent un chinois solide. D'autres langues sont prises en charge via MMMLU mais leur qualité diminue.
• Il est en retard par rapport aux meilleurs modèles phares américains sur certains benchmarks de raisonnement. HLE se situe à 30, et la couverture du SCMP note que Hy3 est comparable aux meilleurs modèles chinois mais toujours derrière les modèles phares actuels d'OpenAI et de Google DeepMind sur les suites de raisonnement les plus difficiles.

Le chemin rapide du développeur : Hy3 Preview plus Apidog

Le curl en ligne de commande est bien pour une démo. Pour une véritable itération, un client API visuel fait gagner des heures.

1. Ouvrir Apidog et créer un nouveau projet. Importez la spécification OpenAPI des complétions de chat OpenAI ; OpenRouter utilise le même schéma.
2. Définissez l'URL de base sur https://openrouter.ai/api/v1 et ajoutez une variable d'environnement pour OPENROUTER_API_KEY.
3. Créez une requête qui cible /chat/completions avec le modèle défini sur tencent/hy3-preview:free.
4. Dupliquez la requête pour comparer les modes de raisonnement. Apidog vous permet de dupliquer une requête et de modifier un paramètre, afin que vous puissiez exécuter le même prompt avec no_think, low et high côte à côte et inspecter la latence et la différence de sortie.
5. Enregistrez les modèles de prompts. Les prompts agentiques peuvent devenir longs. Le système d'environnement et de variables d'Apidog sépare les prompts système, les schémas d'outils et les tours d'utilisateur afin que vous puissiez les réutiliser dans différents tests.

Si vous venez de Postman, le changement est rapide ; notre guide de test d'API sans Postman en 2026 couvre la migration. Les équipes qui vivent dans leur éditeur peuvent exécuter le même workflow à l'intérieur de VS Code avec Apidog à l'intérieur de VS Code, ce qui permet d'ajuster les prompts à côté du code qui consomme la sortie.

Alternatives gratuites lorsque vous atteignez la limite

Si le pool gratuit d'OpenRouter vous limite pendant les heures de pointe, deux pistes valent la peine d'être explorées en premier.

• Espace Hugging Face. L'espace Hy3-preview héberge une démo de chat par navigateur. Il n'est pas scriptable, mais il est gratuit et utile pour des comparaisons rapides.
• Autres modèles chinois à poids ouverts gratuits. Le Qwen 3.5 Omni d'Alibaba propose un niveau gratuit avec une sortie multimodale puissante ; consultez notre annonce du Qwen 3.5 Omni et son guide d'utilisation pour la configuration. Zhipu GLM 5V Turbo est une autre option avec un niveau gratuit généreux ; le guide API du GLM 5V Turbo contient la procédure complète.

Aucun de ceux-ci ne correspond aux chiffres de Hy3 pour SWE-bench et Terminal-Bench en matière de codage agentique, mais ils couvrent des cas d'utilisation de chat, multilingues et multimodaux que le niveau gratuit de Hy3 ne priorise pas. Pour une construction de production, téléchargez Apidog et configurez une collection par modèle ; les benchmarks côte à côte sur vos prompts réels sont plus efficaces que la lecture de n'importe quel classement.

Auto-hébergement de Hy3 Preview avec vLLM

Si vous disposez du matériel, l'inférence locale est la quatrième voie gratuite. La fiche du modèle recommande vLLM avec un parallélisme tensoriel de 8 et la prédiction multi-jetons activée pour le décodage spéculatif :

vllm serve tencent/Hy3-preview \
  --tensor-parallel-size 8 \
  --speculative-config.method mtp \
  --speculative-config.num_speculative_tokens 1 \
  --tool-call-parser hy_v3 \
  --reasoning-parser hy_v3 \
  --enable-auto-tool-choice \
  --served-model-name hy3-preview

La commande SGLang équivalente utilise --tool-call-parser hunyuan et --reasoning-parser hunyuan. Une fois le serveur démarré à http://localhost:8000/v1, n'importe quel SDK OpenAI le cible de la même manière qu'il ciblerait OpenRouter ; seuls l'URL de base et la clé changent.

Attendez-vous à huit GPU de classe H100 en BF16 pour le modèle complet. Des versions communautaires quantifiées apparaîtront, mais au lancement, le chemin officiel est la pleine précision.

FAQ

Hy3 Preview est-il gratuit ?Oui. OpenRouter liste tencent/hy3-preview:free avec 0 $ par million de jetons d'entrée et 0 $ par million de jetons de sortie. Les jetons de raisonnement sur le niveau gratuit sont également gratuits, bien qu'ils comptent dans les limites de débit. Confirmez le statut actuel sur la page du modèle OpenRouter avant de vous y fier pour la production.

Comment Hy3 Preview se compare-t-il à DeepSeek V3 et Qwen 3 ?Le score SWE-bench Verified de Hy3 Preview de 74,4 et Terminal-Bench 2.0 de 54,4 le placent au même niveau que les meilleurs modèles ouverts chinois, avec une nette orientation agent et utilisation d'outils. Pour le chat pur, Qwen 3 et DeepSeek V3 sont compétitifs ; pour les workflows d'agent et de codage, l'utilisation d'outils entraînée par RL de Hy3 est le facteur de différenciation.

Quels sont les modes de raisonnement de Hy3 ?Trois : no_think (par défaut, réponse directe), low et high. Changez-les via le paramètre reasoning sur OpenRouter ou via chat_template_kwargs={"reasoning_effort": "high"} lors de l'appel direct du modèle. Utilisez high pour la planification, le code multi-étapes et les mathématiques ; désactivez-le pour le chat.

Puis-je utiliser Hy3 Preview commercialement ?Oui, sous la licence communautaire Tencent Hy. La licence autorise l'utilisation commerciale avec attribution et conformité aux politiques d'utilisation. Lisez les conditions complètes sur le dépôt GitHub de Hy3 avant de le déployer dans un produit générateur de revenus.

Quelle longueur de contexte le niveau gratuit prend-il en charge ?256K jetons de bout en bout. La liste d'OpenRouter indique 262 144 jetons, correspondant à la fiche du modèle. Vous pouvez coller une base de code entière de taille moyenne et avoir encore de la place pour les schémas d'outils et l'historique de conversation.

Comment tester Hy3 Preview sans écrire de code ?Utilisez l'espace Hugging Face pour une démo de chat par navigateur, ou pointez Apidog vers le point d'accès OpenRouter. Apidog importe la spécification OpenAPI d'OpenAI, donc la configuration de la requête se fait en trois champs : URL de base, clé API et nom du modèle.