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.

Disponibilité du service

Démarrage rapide

Pour un compte existant autorisé à utiliser l’API, trois éléments sont nécessaires :

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. Model : l'un des 16 modèles pris en charge — par ex. gpt-5.4-mini ou claude-sonnet-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

La surface publique stable est décrite ci-dessous et dans le document OpenAPI 3.1 lisible par machine. Les champs non répertoriés peuvent être transmis au fournisseur, mais ne font pas automatiquement partie du contrat de compatibilité de SUB&SUB.

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/responses

OpenAI Responses API — la nouvelle forme de demande OpenAI (client.responses.create(...)). Fonctionne avec tous les modèles de catalogue : gpt-* nativement, claude-* via le même pont de compatibilité que le chat/les complétions. L'utilisation est mesurée de manière identique : jetons d'entrée/sortie au tarif de niveau du modèle.

Exemple Responses exécutable :

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

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).

Exemple Anthropic Messages exécutable :

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

Comptez un prompt au format Anthropic avant de l’envoyer. Utilisez les mêmes champs x-api-key, anthropic-version, model, system, messages et tools que pour /v1/messages. Ce point de terminaison n’est pas facturé. Le suffixe :online est retiré, mais aucun résultat de recherche n’est récupéré ni compté.

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

Listez les modèles que vous pouvez réellement utiliser. Le relais vérifie l'état des deux familles en amont et renvoie les 16 identifiants publics vérifiés - la même liste blanche que les points de terminaison POST appliquent, de sorte que la découverte n'annonce jamais un modèle qui serait 400. Si le catalogue en amont est inaccessible, le point de terminaison 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-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

Contrat de compatibilité

Compatible OpenAI ne signifie pas que tous les champs de tous les modèles upstream sont garantis sur chaque route. Trois niveaux de prise en charge s’appliquent :

Modèles disponibles

Deux familles en amont. Les 7 modèles OpenAI mènent à des comptes partagés de niveau ChatGPT ; les 9 modèles Claude sont desservis par des comptes officiels Anthropic. Les tarifs par jeton dépendent du niveau (voir Pricing) — 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 jetons de « réflexion » avant d'émettre une sortie visible. Définissez reasoning_effort sur le corps de la demande OpenAI /v1/chat/completions (ou reasoning: {"effort": ...} sur /v1/responses) pour contrôler le budget. Pour Claude, utilisez les champs Anthropic-natifs thinking et output_config.effort — 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]

Exemple Python de streaming exécutable :

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

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 :

Nouvelles tentatives et fiabilité

Limitez le nombre de tentatives. Le relais repose sur une capacité upstream partagée et les requêtes de génération ne sont pas idempotentes.

• Réessayer : les réponses 429, 502, 503 et les 500 clairement transitoires. Respectez retry-after ; sinon, utilisez un backoff exponentiel avec jitter (par exemple 1 s, 2 s, 4 s ; trois tentatives maximum).
• Ne pas réessayer sans modification : 400, 401, 402 ou 403. Corrigez d’abord le payload, la clé, le solde ou l’état d’accès.
• Risque de doublon : chaque génération réussie est une requête facturable distincte. SUB&SUB ne déduplique pas actuellement les POST de génération par clé d’idempotence ; conservez un identifiant d’opération côté application et ne réessayez pas après une réponse complète.
• Streaming : un flux SSE interrompu ne peut pas reprendre. Une reconnexion lance une nouvelle génération et peut entraîner une deuxième facturation.

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 Fable et Ultra correspondent aux prix catalogue publiés par Anthropic. Sonnet 5 utilise le tarif de lancement de 2 $/10 $ de Anthropic jusqu'au 31 août 2026 ; son prix standard publié après cette date est de 3 $/15 $. Les autres niveaux fonctionnent en dessous des tarifs en amont grâce au support d'abonnement mutualisé.

Les jetons de raisonnement (lorsque vous définissez reasoning_effort sur OpenAI, ou le champ thinking natif de Anthropic sur Claude) comptent comme des jetons output au taux de niveau du modèle - il n'y a pas de supplément distinct pour un effort élevé, mais une requête réfléchie peut facilement émettre 10 à 50 fois plus de jetons de sortie qu'un sans effort, donc le billet d'un dollar évolue avec lui.

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 tokens de cache sont détaillés dans le relevé de facturation de chaque requête — la console affiche 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 capacité upstream partagée et le throttling côté fournisseur s'appliquent toujours ; si tu les atteins, le relais renvoie 429 avec un en-tête retry-after. Les limites RPM / TPM par clé sont prévues.

État et assistance

• Les comptes connectés autorisés à utiliser l’API voient l’état des fournisseurs dans Console → État du service et les annonces opérationnelles dans Avis système.
• Pour toute aide relative au compte, à la facturation, à la confidentialité ou à la sécurité, écrivez à [email protected].
• Pour signaler une erreur API, indiquez l’horodatage UTC, le point de terminaison, le modèle, le statut HTTP et le préfixe visible de la clé. N’envoyez jamais la clé complète ni le contenu du prompt, sauf demande explicite d’une reproduction expurgée par l’assistance.
• Le service fonctionne au mieux de nos moyens et sans SLA. Consultez les Conditions d’utilisation, disponibles uniquement en anglais, pour la disponibilité et les remboursements, et la Politique de confidentialité pour le traitement des données.

Documentation révisée pour la dernière fois le 14 juillet 2026.