Un relais de l'API Moonshot ajoute une couche entre votre activité et la plateforme officielle. Il peut apporter un point d'entrée unifié, une facturation en yuans, le changement de modèle et la bascule en cas d'incident ; il peut aussi introduire un modèle substitué, une base de facturation floue, une fuite de clé et un point de défaillance supplémentaire. En 2026, Moonshot a remplacé ses modèles principaux par Kimi K3 et la série K2.7 et retiré moonshot-v1 ; si la couche de relais n'a pas mis à jour sa table de modèles, des problèmes silencieux apparaissent : « l'interface répond, mais le résultat est faux ».

Cet article ne recommande aucun prestataire : il explique comment juger, rapprocher et migrer. Les modèles et tarifs font foi sur Tarifs et modèles.

Note : Moonshot, Kimi et Moonshot AI (Yuezhianmian) sont des marques ou marques déposées de Beijing Moonshot Technology Co., Ltd. Cet article est une discussion technique sans lien de filiale avec les titulaires ; les qualifications, conditions et règles de facturation de chaque relais sont fournies par le prestataire et doivent être vérifiées avant signature.

I. Distinguer quatre formes de relais

Le terme « relais » est souvent employé à tort pour désigner au moins quatre modèles, aux responsabilités très différentes :

  • Passerelle hébergée : le prestataire maintient un point d'entrée unique, avec sous-clés, statistiques d'usage, routage de modèles et factures. Vous achetez un service technique et des quotas.
  • Revente / distribution : le prestataire revend des quotas depuis son propre compte amont, éventuellement avec un multiplicateur ou un forfait. L'identité et le niveau du compte amont déterminent directement la stabilité.
  • Passerelle auto-hébergée : vous déployez vous-même un logiciel comme one-api ou new-api, en conservant vos clés amont. Contrôle maximal, mais exploitation, mises à jour et reprise à votre charge.
  • Place de marché cloud ou plateforme d'agrégation : souscription via un fournisseur cloud ou une plateforme, facturation rattachée à la plateforme, gamme parfois plus large, mais il faut aussi vérifier l'amont et les clauses de données.

Déterminez d'abord si vous achetez un « service technique » ou des « quotas de modèle », puis parlez prix : le responsable en cas d'incident n'est pas le même.

II. Clés et mappage des modèles : le risque le plus négligé

Le relais voit l'intégralité des requêtes et des réponses sur le chemin : c'est une conséquence de l'architecture, pas une question de confiance. Pour les requêtes contenant des données personnelles, des contrats ou du code interne, vérifiez d'abord si les données sont persistées, pendant combien de temps, et si elles servent à l'entraînement ; au besoin, anonymisez ou passez en direct.

Plus insidieux encore que les données : le mappage des modèles. Risques fréquents :

  • Un ancien nom de modèle est silencieusement redirigé vers un modèle moins cher ou plus court : l'interface ne renvoie pas d'erreur, mais la qualité baisse.
  • En pic, la requête est dégradée vers un canal inférieur, tandis que le champ model de la réponse ne change pas.
  • Les clés des sites chinois et international sont mélangées : tout fonctionne en temps normal, puis un contrôle de région provoque soudain un 401.
  • Plusieurs clients partagent le même compte amont : la concurrence des autres sature le pool et vous subissez les 429.
  • Le compte amont déclenche une limitation pour comportement anormal, limitation qui peut être impossible à lever.

Le contrat doit donc préciser la table de mappage des modèles, les règles de dégradation et le mécanisme de notification. Exigez au minimum que le relais conserve dans la réponse le model réel, le usage et le request_id, et permette l'export des journaux de requêtes.

III. Transparence de la facturation : transformer la base en tableau de rapprochement

Le K3 actuel de Moonshot facture séparément les entrées avec cache touché, sans cache, les écritures de cache et les sorties ; les écritures de cache distinguent en outre plusieurs durées de vie (TTL). Si le relais ne donne qu'un « total de tokens », vous ne pouvez ni vérifier que le cache a réellement fonctionné, ni contrôler le multiplicateur.

Élément à rapprocher Ce qu'il faut vérifier Écart fréquent
Écriture de cache Facturée séparément, quelle TTL Écriture de cache comptée comme entrée normale
Entrée avec cache touché Remise appliquée sur la partie touchée Tout facturé au prix sans cache
Entrée sans cache Cohérente avec la base officielle Tokens d'entrée gonflés
Tokens de sortie Incluent-ils le raisonnement Base des tokens de raisonnement floue
Requêtes en réessai Double facturation Un dépassement réessayé compté deux fois
Requêtes en échec Traitement des 429, 5xx, déconnexions Facturation même en cas d'échec
Recherche et lots Facturation séparée Intégrés à la facture de dialogue

Quatre questions avant signature : l'unité de facturation est-elle le token, le forfait ou le multiplicateur ? Existe-t-il un minimum de consommation et un préavis de hausse ? Les échecs et réessais sont-ils facturés ? Qui émet la facture et sous quelle rubrique ? Si le prix est nettement inférieur à l'officiel, demandez si cela vient d'un achat en volume, d'une subvention ou d'un quota partagé, sans vous arrêter au chiffre.

IV. Latence et erreurs : les indicateurs à surveiller

Une mesure ponctuelle ne veut rien dire ; observez au moins une semaine. Figez un lot de requêtes et enregistrez séparément :

  • TTFT : délai du premier token, plus représentatif de l'expérience que la durée totale en streaming.
  • Latence p50 / p95 : regardez la queue de distribution, pas la moyenne.
  • Taux d'erreur : distinguez 401, 403, 404, 429, 499, 5xx et error.type.
  • Dimensions de modèle : analysez séparément les performances d'un même appel selon le modèle et le canal.
  • Cohérence de l'usage : le usage de la réponse correspond-il à la facture ?

Voici une sonde minimale, destinée uniquement à valider la chaîne et à relever les indicateurs :

import os, time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RELAY_KEY"],
    base_url=os.environ["RELAY_BASE"],
    max_retries=0,
)

start = time.time()
try:
    resp = client.chat.completions.create(
        model=os.environ["MODEL"],
        messages=[{"role": "user", "content": "Répondez uniquement OK"}],
        max_completion_tokens=16,
    )
    elapsed = time.time() - start
    print({
        "ok": True,
        "latency_ms": round(elapsed * 1000),
        "model": resp.model,
        "usage": resp.usage.model_dump() if resp.usage else None,
        "request_id": resp.id,
    })
except Exception as exc:
    print({"ok": False, "latency_ms": round((time.time() - start) * 1000),
           "error": type(exc).__name__, "detail": str(exc)[:200]})

En production, écrivez les résultats dans une base temporelle et agrégez par heure les p50, p95, taux d'erreur et distribution des modèles. Alerter sur « échec » sans distinguer le type de 429 ne permet pas à l'astreinte de savoir s'il faut ralentir, recharger ou basculer.

V. Liste de migration : de la connexion directe vers un relais

  1. Inventoriez les noms de modèles et vérifiez si moonshot-v1, retiré, est encore utilisé ; migrez d'abord vers kimi-k3, kimi-k2.7 ou kimi-k2.6.
  2. Figez un lot de requêtes de régression couvrant questions courtes, textes longs, streaming, appels d'outils et entrées d'images.
  3. Envoyez le même lot en direct et via le relais, puis comparez model, usage, request_id et qualité de sortie.
  4. Validez les formats d'API réellement utilisés : Chat Completions, Responses ou Anthropic Messages ; n'en testez pas un seul.
  5. Vérifiez que le streaming renvoie bien chaque bloc et se termine correctement, et que le proxy intermédiaire ne désactive pas la mise en tampon.
  6. Provoquez délibérément des 401, 404 et 429 pour vérifier que les types d'erreur et messages sont lisibles et correctement mappés côté client.
  7. Rapprochez la facture réelle et le usage, en couvrant cache, réessais et requêtes en échec.
  8. Déployez progressivement sur une activité à faible risque, conservez un interrupteur de retour au direct, et observez au moins une semaine avant de basculer le trafic critique.

La migration ne se limite pas à l'URL de base et à la clé. Les noms de modèles, paramètres, types d'erreur, statistiques d'usage et circuits de facturation sont les points qui posent le plus de problèmes après la bascule.

VI. Comment vérifier un relais

La vérification combine plusieurs signaux ; un indicateur isolé ne prouve pas l'origine :

  • Le model de la réponse correspond-il à la requête, sans dégradation non annoncée ?
  • La structure usage est-elle complète, avec des champs de cache conformes à la base officielle ?
  • Le request_id est-il traçable et rapprochable des journaux du relais ?
  • Comparez les sorties à la connexion directe sur un jeu d'évaluation fixe, pour vérifier la stabilité de la qualité et de la latence.
  • Les trois formats d'API sont-ils pris en charge, et les extensions de paramètres transmises conformément à l'officiel ?
  • La réponse d'erreur conserve-t-elle error.type, au lieu d'être uniformément présentée comme « erreur de service » ?
  • L'entité de facturation, l'entité contractante et l'entité payeuse sont-elles identiques ?
  • Existe-t-il une page d'état, un SLA, des notifications d'incident et un historique de disponibilité ?

Si le relais ne fournit pas ces informations, il ne convient pas à une activité critique. La période de test doit couvrir au moins un cycle de facturation complet, pour éviter un début de mois normal et une limitation en fin de mois.

VII. Concevoir la sortie dès le départ

Le coût caché principal d'une couche de relais est la dépendance. Avant signature, vérifiez : la clé peut-elle être révoquée à tout moment ? Les sous-clés peuvent-elles être isolées par projet ? Les journaux sont-ils exportables ? Le solde non consommé est-il remboursable ? Sous quel délai les données sont-elles supprimées ? Quel préavis pour une hausse tarifaire ? Un coût de migration faible laisse une marge de négociation.

Une passerelle auto-hébergée pose aussi la question de la sortie : versions logicielles, plugins, base de données et clés amont restent chez vous, mais sans maintenance, les mises à jour et correctifs de sécurité prennent du retard. Choisir l'auto-hébergement, c'est accepter ce coût humain de long terme.

Questions fréquentes

Un relais est-il toujours plus stable que la connexion directe ?

Non. Un relais peut offrir réessais, file d'attente et bascule, mais ajoute un point de défaillance. La stabilité dépend de l'exploitation du prestataire, de la qualité du compte amont et de vos délais d'attente ; validez-la sur au moins une semaine de trafic réel.

Un prix inférieur à l'officiel est-il normal ?

Cela peut venir d'un achat en volume, d'une subvention ou d'un quota partagé, ou de la base de facturation. Demandez l'unité de facturation, les règles de cache et le traitement des échecs, puis vérifiez avec la facture.

Un proxy auto-hébergé résout-il les 429 ?

Il n'ajoute pas de quota amont. Un proxy peut mettre en file, ralentir, réessayer et basculer ; si la concurrence ou le TPD du compte amont sont atteints, il faut attendre la réinitialisation ou monter de niveau.

Comment savoir si un relais utilise réellement Moonshot ?

Examinez model, usage et request_id dans la réponse, puis comparez avec la connexion directe sur un jeu d'évaluation fixe. La vérification combinée est plus fiable qu'un indicateur isolé ; en cas de doute sur l'origine, privilégiez le direct.

Combien de code faut-il modifier pour passer à un relais ?

Un projet compatible OpenAI ne change généralement que l'URL de base, la clé et le nom de modèle. Le streaming, les délais d'attente, le mappage des erreurs et les statistiques d'usage doivent en revanche être retestés : ce sont les points les plus fragiles après la bascule.

Pour aller plus loin

Créez d'abord une clé de test sur la passerelle IA ZSQH, exécutez la sonde et la liste de migration de cet article, puis décidez quelles activités restent en direct et lesquelles passent par la passerelle. Les modèles, bases de facturation et disponibilités font foi sur Tarifs et modèles.

Lectures associées :