Référence de l'API

SUB&SUB expose un relais multi-fournisseurs sur https://api.subnsub.com/v1. Les clients OpenAI appellent /v1/chat/completions ; les clients Anthropic appellent /v1/messages. La même clé sk-cf-... route les deux — choisis le modèle dans le corps de la requête et le relais choisit l'upstream.

Démarrage rapide

Trois choses dont tu as besoin :

1. URL de base : https://api.subnsub.com/v1 (clients OpenAI) ou https://api.subnsub.com (clients Anthropic — le SDK ajoute lui-même /v1/messages)
2. Clé API : sk-cf-... émise depuis la console
3. Modèle : l'un des 21 modèles vérifiés — par ex. gpt-5.4-mini ou claude-haiku-4.5

Authentification

Chaque requête doit porter un en-tête Authorization: Bearer sk-cf-.... Les clés sont émises depuis la console et stockées sous forme de hachages SHA-256 — une fois que tu quittes l'écran de création, le texte clair est perdu pour toujours, alors enregistre-le immédiatement.

Endpoints

POST /v1/chat/completions

Envoie une requête de complétion de chat. Le format de la requête correspond à l'API Chat Completions d'OpenAI — les SDK OpenAI fonctionnent sans modification.

POST /v1/messages

Endpoint Anthropic natif pour les modèles claude-* — le SDK Anthropic (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) fonctionne sans modification sur ce chemin. Pointe ton URL de base vers https://api.subnsub.com et authentifie-toi via l'en-tête x-api-key (la forme Authorization-Bearer fonctionne aussi, si ton client la préfère).

GET /v1/models

Liste les modèles que tu peux réellement appeler. Le relais fusionne les catalogues OpenAI et Anthropic de sub2api et les filtre pour ne garder que les 21 que nous avons testés de bout en bout sur le pool de comptes actuel — les ID fantômes qui renvoient 503 au moment du routage, ou un 400 upstream au premier token, sont masqués. Si tous les upstreams configurés sont injoignables, l'endpoint renvoie 502 models_unreachable plutôt qu'une liste vide trompeuse.

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-4.5", "type": "model", ... },
    { "id": "claude-haiku-4.5",  "type": "model", ... },
    ...
  ]
}

Modèles disponibles

Deux familles d'upstream. Les 7 modèles OpenAI routent vers des comptes partagés de la gamme ChatGPT ; les 14 modèles Claude routent via un proxy inverse Kiro vers AWS CodeWhisperer. Les tarifs par token dépendent du tier (voir Tarifs) — la même clé fonctionne pour les deux.

OpenAI

Anthropic

Effort de raisonnement

Chaque modèle OpenAI ci-dessus est un modèle de raisonnement — le backend peut dépenser plus ou moins de tokens de « réflexion » avant de produire une sortie visible. Définis reasoning_effort dans le corps de la requête OpenAI /v1/chat/completions pour contrôler le budget. Pour Claude, utilise le champ de requête Anthropic natif thinking (ou choisis une variante de modèle -thinking) — voir la section /v1/messages. Les modèles OpenAI acceptent les mêmes cinq valeurs d'effort :

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

Streaming

Définis "stream": true pour recevoir des Server-Sent Events. Le chunk final porte un bloc usage (nous forçons stream_options.include_usage en upstream pour que les comptes de tokens soient toujours émis), puis un data: [DONE] littéral ferme le flux.

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

Recherche web

Ajoute :online à n'importe quel ID de modèle pris en charge par l'endpoint et le relais lancera une recherche web avant de transmettre au modèle, en préfixant la conversation avec les résultats pour que la réponse s'appuie sur des données fraîches. Le suffixe fonctionne sur /v1/chat/completions et /v1/messages (ce dernier exige toujours une base claude-*) ; aucun champ de requête spécifique à la recherche n'est requis.

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

Comment ça marche : le relais retire :online, prend le message utilisateur le plus récent comme requête (limité à 400 caractères), appelle Tavily pour un maximum de 3 résultats avec le texte de page extrait lorsqu'il est disponible, plus un résumé optionnel généré par Tavily, puis les préfixe à ce même tour utilisateur sous forme de bloc <search_results> clairement délimité avant d'envoyer la requête à l'upstream. L'appel de recherche a un délai d'expiration de 8 secondes. Les résultats sont délibérément injectés dans le rôle utilisateur — jamais dans le prompt système — afin que des extraits non fiables ne puissent pas être élevés au rang d'instructions de priorité système.

Le bloc <search_results> ressemble à ceci. Il est précédé d'une instruction sur une ligne indiquant au modèle de traiter le bloc comme des données externes non fiables et de citer les éléments numérotés en ligne :

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

Quand utiliser :online

Le relais effectue un seul appel Tavily par requête et injecte les résultats — ce n'est pas une boucle de recherche agentique. Le modèle ne décide pas de relancer une recherche en fonction de ce qu'il voit, comme le font Perplexity Sonar ou l'outil de navigation de ChatGPT. Planifie en tenant compte de cette limitation :

Formule le dernier message utilisateur comme une requête de recherche autonome. La recherche s'effectue sur le texte littéral de ton tour utilisateur le plus récent (limité à 400 caractères), donc des relances conversationnelles comme « et qu'en est-il de la dernière version ? » deviennent des requêtes inutiles sans contexte. Dans un chat multi-tours, redonne le sujet quand tu ajoutes :online — par ex. « dernière version du SDK Python Anthropic » plutôt que « la dernière ».

Pour les questions nécessitant une synthèse en plusieurs étapes (comparaison, recherche approfondie), décompose-les en plusieurs tours et ajoute :online à chacun. Le modèle lira les résultats frais de chaque tour ; tu orientes manuellement la requête suivante. Note que le bloc <search_results> injecté n'est envoyé qu'à l'upstream — il n'est pas renvoyé à ton client et n'est pas conservé pour la requête suivante, donc si un tour ultérieur dépend de détails de sources antérieures, demande au modèle de les résumer dans sa réponse visible. Le mode recherche en une seule fois n'est pas pris en charge.

Erreurs

L'enveloppe dépend de l'endpoint que tu as appelé — le relais renvoie les erreurs dans le protocole correspondant au SDK de l'appelant, et les erreurs upstream sont transmises telles quelles.

Chemins OpenAI (/v1/chat/completions, /v1/responses, /v1/models) — enveloppe OpenAI :

{ "error": { "message": "...", "type": "...", "code": "..." } }

Chemins Anthropic (/v1/messages, /v1/messages/count_tokens) — enveloppe Anthropic :

{ "type": "error", "error": { "type": "...", "message": "..." } }

L'enveloppe Anthropic utilise un format différent — pas de champ code, et le discriminateur type: "error" est au niveau racine (avec l'error.type interne donnant la catégorie, par ex. authentication_error, invalid_request_error, permission_error, api_error). Les SDK Anthropic analysent déjà ce format ; les gestionnaires d'erreurs du SDK OpenAI standard ne le feront pas, alors appelle /v1/messages avec un SDK Anthropic (ou fais du HTTP brut).

Les codes de statut sont les codes HTTP canoniques dans les deux protocoles :

Tarifs & facturation

Paiement à l'usage, facturé par token en microdollars (1 micro = $0.000001 = 1/10,000 de cent) pour que les requêtes inférieures au cent soient suivies précisément. Les tarifs sont par 1M tokens, par tier — voir le tableau des modèles pour savoir à quel tier chaque modèle correspond.

Les tarifs du tier Ultra correspondent au tarif public d'Opus publié par Anthropic — répercussion directe, sans marge. Les autres tiers tournent en dessous de leurs tarifs upstream grâce au socle d'abonnements mutualisés.

Les tokens de raisonnement (quand tu définis reasoning_effort sur OpenAI, ou utilises une variante Claude -thinking) comptent comme des tokens de sortie au tarif du tier du modèle — il n'y a pas de supplément distinct pour un effort élevé, mais une requête à réflexion approfondie peut facilement émettre 10–50× plus de tokens de sortie qu'une requête sans effort, donc la facture en dollars évolue en conséquence.

Le prompt-caching Anthropic est facturé comme une ligne distincte : écritures de cache à 1.25× et lectures de cache à 0.10× du tarif d'entrée du tier. Ainsi, un cache hit haiku-4.5 coûte 0.20 × 0.10 = $0.02 per 1M tokens, et un cache hit sonnet-4.5 coûte 0.75 × 0.10 = $0.075 per 1M tokens. Les colonnes de cache sont enregistrées sur chaque ligne de règlement pour que la console puisse afficher le détail.

Le solde est déduit en temps réel à mesure que chaque requête se termine — pour les requêtes en streaming, le règlement s'exécute après l'arrivée du chunk [DONE]. Consulte ton solde en direct et les règlements par requête sur /console#billing.

Limites de débit

Pas de limites de débit par clé aujourd'hui. La concurrence du pool de comptes upstream & le throttling côté serveur d'OpenAI s'appliquent ; si tu les atteins, le relais renvoie 429 avec un en-tête retry-after. Les limites RPM / TPM par clé arriveront après le MVP.